How do I expose a Rust function to Lua using hlua?

Wrap your Rust function with hlua::functionX where X is the number of parameters, then use lua.set to add it as a global variable. For example, hlua::function2(add) exposes a two-parameter function, and Lua can call it directly.

hlua vs rlua: which should I use for embedding Lua in Rust?

hlua focuses on high-level safety and ease of use for Lua 5.2, while rlua often supports newer Lua versions and might offer different trade-offs. Choose hlua if you prioritize a straightforward API and Lua 5.2 compatibility; consider rlua for Lua 5.3+ features or different design goals.

Can I use hlua with LuaJIT?

hlua is designed for Lua 5.2, so it may not be compatible with LuaJIT which is based on Lua 5.1. You might need to look for alternative bindings or forks if LuaJIT support is required for your project.

How to handle errors when executing Lua code in hlua?

The execute method returns a Result , so use Rust's error handling like unwrap or match. If a Rust function returns a Result with an error, it triggers a Lua error, allowing integrated error propagation between Rust and Lua.

Is hlua thread-safe for concurrent Lua contexts?

The Lua struct requires mutable access and holds references, so sharing across threads is challenging without synchronization. Typically, you manage separate Lua contexts per thread or use Rust's concurrency primitives to ensure safety, as enforced by the ownership model.

How to read a Lua table into a Rust HashMap with hlua?

Use lua.get to read into a HashMap , as shown in the README. Ensure the table keys are hashable, and handle conversions; for example, Lua tables with mixed keys can be read directly into HashMaps.

hlua — Rust Lua Binding

What is hlua?

hlua is a Rust library that provides a high-level binding for Lua 5.2, allowing Rust applications to safely interface with the Lua scripting language. It enables executing Lua code, reading/writing variables, exposing Rust functions, and manipulating Lua tables without direct stack access. The library solves the problem of embedding Lua in Rust with type safety and ergonomic APIs.

Target Audience

Rust developers who need to embed Lua scripting in their applications, such as game developers, tool creators, or those building extensible systems. It's ideal for those who want safe, high-level interaction with Lua without dealing with low-level C APIs.

Value Proposition

Developers choose hlua over lower-level bindings because it offers a safe, idiomatic Rust API that prevents common errors like stack misuse, provides seamless type conversions, and includes features like container support and user data. Its focus on safety without sacrificing functionality makes it a robust choice for embedding Lua.

Rust library to interface with Lua

Use Cases

Best For

Embedding Lua scripting in Rust-based game engines
Creating extensible tools or plugins with Lua in Rust
Automating tasks by exposing Rust functions to Lua scripts
Prototyping game logic with Lua while using Rust for performance
Building configuration systems where Lua scripts define behavior
Developing modding APIs for Rust applications with Lua support

Not Ideal For

Projects requiring Lua 5.3 or higher features for modern scripting capabilities
Developers needing low-level access to the Lua stack for custom performance optimizations
Applications where binding stability is critical, due to the unstable user data API
Teams that require reading sparse or complex Lua tables directly into Rust Vecs without limitations

Pros & Cons

Pros

Type Safety Enforcement

Ensures safe variable access by enforcing Rust types like i32 and bool when reading/writing Lua globals, preventing type mismatches at compile time.

Ergonomic API Abstraction

Abstracts the Lua stack with simple methods like set and get, making it easy to execute Lua code and manipulate tables without low-level details.

Seamless Function Exposure

Allows wrapping Rust functions and closures for Lua calls with compile-time lifetime checks, ensuring memory safety.

Container Integration

Supports reading and writing Rust containers like Vec and HashMap to/from Lua tables, simplifying data exchange between the languages.

Cons

Outdated Lua Binding

Only supports Lua 5.2, lacking features from newer versions like integer division in Lua 5.3, which may hinder adoption in modern projects.

Unstable Advanced APIs

The user data API is marked as 'very unstable' in the README, leading to potential breaking changes and increased maintenance burden for custom types.

Limited Table Reading

Cannot read all Lua tables into Rust Vecs; for example, sparse arrays or non-numeric keys result in None, restricting data handling flexibility.

Potential Performance Cost

High-level abstractions may add overhead compared to direct C bindings, which could be a concern in performance-sensitive applications.

What is hlua?

Target Audience

Value Proposition

Use Cases

Best For

Embedding Lua scripting in Rust-based game engines
Creating extensible tools or plugins with Lua in Rust
Automating tasks by exposing Rust functions to Lua scripts
Prototyping game logic with Lua while using Rust for performance
Building configuration systems where Lua scripts define behavior
Developing modding APIs for Rust applications with Lua support

Not Ideal For

Projects requiring Lua 5.3 or higher features for modern scripting capabilities
Developers needing low-level access to the Lua stack for custom performance optimizations
Applications where binding stability is critical, due to the unstable user data API
Teams that require reading sparse or complex Lua tables directly into Rust Vecs without limitations

Pros & Cons

Pros

Type Safety Enforcement

Ensures safe variable access by enforcing Rust types like i32 and bool when reading/writing Lua globals, preventing type mismatches at compile time.

Ergonomic API Abstraction

Abstracts the Lua stack with simple methods like set and get, making it easy to execute Lua code and manipulate tables without low-level details.

Seamless Function Exposure

Allows wrapping Rust functions and closures for Lua calls with compile-time lifetime checks, ensuring memory safety.

Container Integration

Supports reading and writing Rust containers like Vec and HashMap to/from Lua tables, simplifying data exchange between the languages.

Cons

Outdated Lua Binding

Only supports Lua 5.2, lacking features from newer versions like integer division in Lua 5.3, which may hinder adoption in modern projects.

Unstable Advanced APIs

The user data API is marked as 'very unstable' in the README, leading to potential breaking changes and increased maintenance burden for custom types.

Limited Table Reading

Cannot read all Lua tables into Rust Vecs; for example, sparse arrays or non-numeric keys result in None, restricting data handling flexibility.

Potential Performance Cost

High-level abstractions may add overhead compared to direct C bindings, which could be a concern in performance-sensitive applications.

hlua

What is hlua?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?

hlua

What is hlua?

Overview

Use Cases

Best For

Not Ideal For

Pros & Cons

Pros

Cons

Frequently Asked Questions

Related Projects

Found a gem we're missing?