Trait mlua::LuaSerdeExt

pub trait LuaSerdeExt: Sealed {
    // Required methods
    fn null(&self) -> Value<'_>;
    fn array_metatable(&self) -> Table<'_>;
    fn to_value<'lua, T: Serialize + ?Sized>(
        &'lua self,
        t: &T
    ) -> Result<Value<'lua>>;
    fn to_value_with<'lua, T>(
        &'lua self,
        t: &T,
        options: Options
    ) -> Result<Value<'lua>>
       where T: Serialize + ?Sized;
    fn from_value<T: DeserializeOwned>(&self, value: Value<'_>) -> Result<T>;
    fn from_value_with<T: DeserializeOwned>(
        &self,
        value: Value<'_>,
        options: Options
    ) -> Result<T>;
}

Available on crate feature serialize only.

Trait for serializing/deserializing Lua values using Serde.

Required Methods

fn null(&self) -> Value<'_>

A special value (lightuserdata) to encode/decode optional (none) values.

Requires feature = "serialize"

Example

use std::collections::HashMap;
use mlua::{Lua, Result, LuaSerdeExt};

fn main() -> Result<()> {
    let lua = Lua::new();
    lua.globals().set("null", lua.null())?;

    let val = lua.load(r#"{a = null}"#).eval()?;
    let map: HashMap<String, Option<String>> = lua.from_value(val)?;
    assert_eq!(map["a"], None);

    Ok(())
}

fn array_metatable(&self) -> Table<'_>

A metatable attachable to a Lua table to systematically encode it as Array (instead of Map). As result, encoded Array will contain only sequence part of the table, with the same length as the # operator on that table.

Requires feature = "serialize"

Example

use mlua::{Lua, Result, LuaSerdeExt};
use serde_json::Value as JsonValue;

fn main() -> Result<()> {
    let lua = Lua::new();
    lua.globals().set("array_mt", lua.array_metatable())?;

    // Encode as an empty array (no sequence part in the lua table)
    let val = lua.load("setmetatable({a = 5}, array_mt)").eval()?;
    let j: JsonValue = lua.from_value(val)?;
    assert_eq!(j.to_string(), "[]");

    // Encode as object
    let val = lua.load("{a = 5}").eval()?;
    let j: JsonValue = lua.from_value(val)?;
    assert_eq!(j.to_string(), r#"{"a":5}"#);

    Ok(())
}

fn to_value<'lua, T: Serialize + ?Sized>( &'lua self, t: &T ) -> Result<Value<'lua>>

Converts T into a Value instance.

Requires feature = "serialize"

Example

use mlua::{Lua, Result, LuaSerdeExt};
use serde::Serialize;

#[derive(Serialize)]
struct User {
    name: String,
    age: u8,
}

fn main() -> Result<()> {
    let lua = Lua::new();
    let u = User {
        name: "John Smith".into(),
        age: 20,
    };
    lua.globals().set("user", lua.to_value(&u)?)?;
    lua.load(r#"
        assert(user["name"] == "John Smith")
        assert(user["age"] == 20)
    "#).exec()
}

fn to_value_with<'lua, T>( &'lua self, t: &T, options: Options ) -> Result<Value<'lua>>

where T: Serialize + ?Sized,

Converts T into a Value instance with options.

Requires feature = "serialize"

Example

use mlua::{Lua, Result, LuaSerdeExt, SerializeOptions};

fn main() -> Result<()> {
    let lua = Lua::new();
    let v = vec![1, 2, 3];
    let options = SerializeOptions::new().set_array_metatable(false);
    lua.globals().set("v", lua.to_value_with(&v, options)?)?;

    lua.load(r#"
        assert(#v == 3 and v[1] == 1 and v[2] == 2 and v[3] == 3)
        assert(getmetatable(v) == nil)
    "#).exec()
}

fn from_value<T: DeserializeOwned>(&self, value: Value<'_>) -> Result<T>

Deserializes a Value into any serde deserializable object.

Requires feature = "serialize"

Example

use mlua::{Lua, Result, LuaSerdeExt};
use serde::Deserialize;

#[derive(Deserialize, Debug, PartialEq)]
struct User {
    name: String,
    age: u8,
}

fn main() -> Result<()> {
    let lua = Lua::new();
    let val = lua.load(r#"{name = "John Smith", age = 20}"#).eval()?;
    let u: User = lua.from_value(val)?;

    assert_eq!(u, User { name: "John Smith".into(), age: 20 });

    Ok(())
}

fn from_value_with<T: DeserializeOwned>( &self, value: Value<'_>, options: Options ) -> Result<T>

Deserializes a Value into any serde deserializable object with options.

Requires feature = "serialize"

Example

use mlua::{Lua, Result, LuaSerdeExt, DeserializeOptions};
use serde::Deserialize;

#[derive(Deserialize, Debug, PartialEq)]
struct User {
    name: String,
    age: u8,
}

fn main() -> Result<()> {
    let lua = Lua::new();
    let val = lua.load(r#"{name = "John Smith", age = 20, f = function() end}"#).eval()?;
    let options = DeserializeOptions::new().deny_unsupported_types(false);
    let u: User = lua.from_value_with(val, options)?;

    assert_eq!(u, User { name: "John Smith".into(), age: 20 });

    Ok(())
}

Object Safety

This trait is not object safe.

Implementors

impl LuaSerdeExt for Lua