lua-assembler 0.0.4

Parse and write Lua .luac bytecode
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81

# Lua Assembler

A versatile toolchain for the Lua programming language, supporting the assembly and disassembly of Lua bytecode across different versions (5.1 - 5.4).

## 🏛️ Architecture

```mermaid
graph TB
    subgraph "Lua Bytecode Toolchain"
        A[Lua Source / Bytecode] --> B[Lua Program Model]
        B --> C[Bytecode Reader/Writer]
        C --> D[Luac View / AST]
        D --> E[Lua Binary (.luac)]
        
        subgraph "Core Engines"
            F[Instruction Builder]
            G[Constant Pool Manager]
            H[Upvalue Resolver]
        end
        
        C --> F
        C --> G
        C --> H
    end
```

## 🚀 Features

### Core Capabilities
- **Version Compatibility**: Handles bytecode format variations between Lua 5.1, 5.2, 5.3, and 5.4.
- **Bi-directional Conversion**: Supports both compiling Lua IR to binary and decompiling `.luac` files back into a structured program model.
- **Instruction Encoding**: Precise encoding of Lua opcodes (iABC, iABx, iAsBx, iAx) including register allocation metadata.

### Advanced Features
- **Header Customization**: Flexible configuration of Lua bytecode headers (endianness, integer size, float size, etc.) for cross-platform compatibility.
- **Constant Management**: Efficient handling of Lua's multi-type constant pools (nil, boolean, number, string).
- **Prototyping**: Support for nested function prototypes and complex upvalue mapping.

## 💻 Usage

### Reading and Writing Lua Bytecode
The following example shows how to read a precompiled Lua file and write it back with a different configuration.

```rust
use lua_assembler::formats::luac::{LuacReadConfig, LuacWriteConfig};
use std::fs::File;

fn main() {
    // 1. Read .luac file
    let input_file = File::open("hello.luac").expect("Failed to open input");
    let read_config = LuacReadConfig::default();
    let reader = read_config.as_reader(input_file);
    let program = reader.read_program().expect("Failed to read program");

    // 2. Modify or Analyze program (optional)
    println!("Main function has {} instructions", program.main_function.instructions.len());

    // 3. Write back to .luac with custom config
    let output_file = File::create("hello_copy.luac").expect("Failed to create output");
    let write_config = LuacWriteConfig::default();
    let writer = write_config.as_writer(output_file);
    writer.write_program(&program).expect("Failed to write program");
}
```

## 🛠️ Support Status

| Lua Version | Bytecode Reading | Bytecode Writing | Instruction Set |
| :--- | :---: | :---: | :--- |
| Lua 5.1 | ✅ | ✅ | Full |
| Lua 5.2 | ✅ | ✅ | Full |
| Lua 5.3 | ✅ | ✅ | Full |
| Lua 5.4 | ✅ | ✅ | Full |
| Luajit | 🚧 | 🚧 | Partial |

*Legend: ✅ Supported, 🚧 In Progress, ❌ Not Supported*

## 🔗 Relations

- **[gaia-types](file:///e:/普遍优化/project-gaia/projects/gaia-types/readme.md)**: Uses the binary I/O primitives to handle the platform-dependent header sizes in Lua bytecode.
- **[gaia-assembler](file:///e:/普遍优化/project-gaia/projects/gaia-assembler/readme.md)**: Serves as a target for Gaia IR when compiling for Lua-based environments (e.g., game engines, embedded scripting).