Update docs

Cargo.toml

@@ -12,12 +12,13 @@ license = "MIT"
 links = "lua"
 build = "build/main.rs"
 description = """
-High level bindings to Lua 5.1/5.2/5.3 (including LuaJIT)
+High level bindings to Lua 5.1/5.2/5.3/5.4 (including LuaJIT)
 with async/await features and support of writing native lua modules in Rust.
 """
 
 [badges]
 # github-actions = { repository = "khvzak/mlua", workflow = "CI" }
+maintenance = { status = "actively-developed" }
 
 [package.metadata.docs.rs]
 features = ["async"]

README.md

@@ -10,17 +10,26 @@
 
 [Guided Tour](examples/guided_tour.rs)
 
-A fork of [rlua 0.15](https://github.com/kyren/rlua/tree/0.15.3) which provides a high level
+`mlua` is bindings to [Lua](https://www.lua.org) programming language for Rust with a goal to provide
-interface between Rust and Lua. Unlike `rlua` , `mlua` supports Lua 5.1 (including LuaJIT), 5.2 and 5.3.
+_safe_ (as far as it's possible), high level, easy to use, practical and flexible API.
-The `mlua` goal is to be an easy to use, practical and flexible API between Rust and Lua but
+
-*__not__* always 100% safe due to the Lua VM nature. Also, `mlua` provides a way to write native lua
+Started as [rlua v0.15](https://github.com/amethyst/rlua/tree/0.15.3) fork, `mlua` supports *__all__* major Lua versions (including LuaJIT) and allows to write native Lua modules on Rust as well as use Lua a standalone mode.
-modules in Rust.
+
+`mlua` supports the following Lua versions (and tested on Windows/macOS/Linux):
+- Lua 5.4 (`feature = "lua54"`)
+- Lua 5.3 (`feature = "lua53"`, enabled by default)
+- Lua 5.2 (`feature = "lua52"`)
+- Lua 5.1 (`feature = "lua51"`)
+- LuaJIT 2.0.5 stable (`feature = "luajit"`), although I'm not encouraging to use this version
+- LuaJIT 2.1.0 beta (`feature = "luajit"`)
+
+Additional `feature = "vendored"` enables building Lua from sources during `mlua` compilation.
 
 ## Usage
 
 ### Async/await support
 
-Starting from 0.3, mlua supports async/await for all Lua versions. This works using Lua [coroutines](https://www.lua.org/manual/5.3/manual.html#2.6) and require running [Thread](https://docs.rs/mlua/latest/mlua/struct.Thread.html) along with enabling `async` feature in `Cargo.toml`.
+Starting from v0.3, `mlua` supports async/await for all Lua versions. This works using Lua [coroutines](https://www.lua.org/manual/5.3/manual.html#2.6) and require running [Thread](https://docs.rs/mlua/latest/mlua/struct.Thread.html) along with enabling `feature = "async"` in `Cargo.toml`.
 
 **Examples**:
 - [HTTP Client](examples/async_http_client.rs)
@@ -29,9 +38,10 @@ Starting from 0.3, mlua supports async/await for all Lua versions. This works us
 
 ### Choosing Lua version
 
-The following features could be used to choose Lua version: `lua53` (default), `lua52`, `lua51` and `luajit`.
+The following features could be used to choose Lua version: `lua54`, `lua53` (default), `lua52`, `lua51` and `luajit`.
+To switch between Lua versions it's required to set `default_features = false` in `mlua` dependency.
 
-By default mlua uses `pkg-config` tool to find lua includes and lib.
+By default `mlua` uses `pkg-config` tool to find lua includes and libraries for the chosen Lua version.
 In most cases it works as desired, although sometimes could be more preferable to use a custom lua library.
 To achieve this, mlua supports `LUA_INC`, `LUA_LIB`, `LUA_LIB_NAME` and `LUA_LINK` environment variables.
 `LUA_LINK` is optional and may be `dylib` (a dynamic library) or `static` (a static library, `.a` archive).
@@ -43,14 +53,14 @@ my_project $ LUA_INC=$HOME/tmp/lua-5.2.4/src LUA_LIB=$HOME/tmp/lua-5.2.4/src LUA
 
 `mlua` also supports vendored lua/luajit using the auxilary crates [lua-src](https://crates.io/crates/lua-src) and
 [luajit-src](https://crates.io/crates/luajit-src).
-Just enable the `vendored` feature and cargo will automatically build and link specified lua/luajit version. This is the easiest way to get started with mlua.
+Just enable the `vendored` feature and cargo will automatically build and link specified lua/luajit version. This is the easiest way to get started with `mlua`.
 
 ### Standalone mode
 Add to `Cargo.toml` :
 
 ``` toml
 [dependencies]
-mlua = "0.3"
+mlua = "0.4"
 ```
 
 `main.rs`
@@ -82,8 +92,8 @@ Add to `Cargo.toml` :
 crate-type = ["cdylib"]
 
 [dependencies]
-mlua = "0.3"
+mlua = "0.4"
-mlua_derive = "0.3"
+mlua_derive = "0.4"
 ```
 
 `lib.rs` :
@@ -106,7 +116,7 @@ fn my_module(lua: &Lua) -> LuaResult<LuaTable> {
 }
 ```
 
-And then (macos example):
+And then (macOS example):
 
 ``` sh
 $ cargo build
@@ -118,15 +128,13 @@ hello, world!
 ## Safety
 
 One of the `mlua` goals is to provide *safe* API between Rust and Lua.
-Every place where the Lua C API may trigger an error longjmp
+Every place where the Lua C API may trigger an error longjmp in any way is protected by `lua_pcall`,
-in any way is protected by `lua_pcall` , and the user of the library is protected
+and the user of the library is protected from directly interacting with unsafe things like the Lua stack,
-from directly interacting with unsafe things like the Lua stack, and there is
+and there is overhead associated with this safety.
-overhead associated with this safety.
 
 Unfortunately, `mlua` does not provide absolute safety even without using `unsafe` .
-This library contains a huge amount of unsafe code. There are almost
+This library contains a huge amount of unsafe code. There are almost certainly bugs still lurking in this library!
-certainly bugs still lurking in this library!  It is surprisingly, fiendishly
+It is surprisingly, fiendishly difficult to use the Lua C API without the potential for unsafety.
-difficult to use the Lua C API without the potential for unsafety.
 
 ## Panic handling
 
@@ -150,10 +158,9 @@ let _ = lua.load(r#"
 unreachable!()
 ```
 
-`mlua` should also be panic safe in another way as well, which is that any `Lua`
+`mlua` should also be panic safe in another way as well, which is that any `Lua` instances or handles
-instances or handles remains usable after a user generated panic, and such
+remains usable after a user generated panic, and such panics should not break internal invariants or
-panics should not break internal invariants or leak Lua stack space. This is
+leak Lua stack space. This is mostly important to safely use `mlua` types in Drop impls, as you should not be
-mostly important to safely use `mlua` types in Drop impls, as you should not be
 using panics for general error handling.
 
 Below is a list of `mlua` behaviors that should be considered a bug.

src/lua.rs

@@ -114,7 +114,7 @@ impl Lua {
     /// Creates a new Lua state and loads the safe subset of the standard libraries.
     ///
     /// # Safety
-    /// The created Lua state would have safety guarantees and would not allow to load unsafe
+    /// The created Lua state would have _some_ safety guarantees and would not allow to load unsafe
     /// standard libraries or C modules.
     #[allow(clippy::new_without_default)]
     pub fn new() -> Lua {
@@ -137,7 +137,7 @@ impl Lua {
     /// Use the [`StdLib`] flags to specifiy the libraries you want to load.
     ///
     /// # Safety
-    /// The created Lua state would have safety guarantees and would not allow to load unsafe
+    /// The created Lua state would have _some_ safety guarantees and would not allow to load unsafe
     /// standard libraries or C modules.
     ///
     /// [`StdLib`]: struct.StdLib.html