Build a Lua Interpreter in Rust

https://wubingzheng.github.io/build-lua-in-rust/en/
Admin
This project documents the implementation of a production-level Lua interpreter from scratch using...
Tokens:90,136
Snippets:766
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### C Lua API Example: Basic Interpreter Setup

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-04

This snippet demonstrates the basic C API usage for the official Lua interpreter. It shows how to create a Lua state, load a file, and execute it using `lua_pcall`. This serves as a comparison to the custom Rust interpreter's approach.

```c
lua_State *L = lua_open(); // Create lua_State
luaL_loadfile(L, filename); // Parse and put the parsing result on the top of the stack
lua_pcall(L, 0, 0, 0); // top of execution stack
```

--------------------------------

### Lua goto Statement Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

An example of using the 'goto' statement with a 'continue' label in Lua. This demonstrates jumping within a while loop, highlighting the handling of local variables and void statements.

```lua
while xx do
     if yy then goto continue end
     local var = 123
     -- some code
     ::continue::
end
```

--------------------------------

### Lua 'Hello, World!' Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

A basic Lua program that prints 'hello, world!' to the console. This serves as the initial target for the custom Lua interpreter being built.

```lua
print "hello, world!"

```

--------------------------------

### Lua Addition Code Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch04-03

A simple Lua code snippet demonstrating variable assignment and addition.

```lua
__
local
local a = 1
local b = 2
r = a + b


```

--------------------------------

### Lua Example: Short-Circuiting 'and'

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates a common Lua code pattern using the 'and' operator for short-circuiting evaluation. This example highlights the need for efficient handling of conditional expressions.

```lua
local x = t and t.k
```

--------------------------------

### Initial Return Bytecode Handling in Rust VM

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

An initial implementation of the 'Return' bytecode handler in Rust. It returns both the starting position and the number of return values from the stack.

```rust
     ByteCode::Return(iret, nret) => {
         return (self. base + iret as usize, nret as usize);
     }
```

--------------------------------

### Eliminating Left Recursion: Prefixexp Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Applies the left recursion elimination technique to the Lua `prefixexp` grammar rule, demonstrating how to resolve ambiguities caused by recursive definitions starting with the same non-terminal.

```lua
Original prefixexp rule (simplified for left recursion):
prefixexp ::= prefixexp '[' exp ']' | prefixexp '.' Name | prefixexp args | prefixexp ':' Name args | Name | '(' exp ')'

Applying elimination:
α = '[' exp ']' | '.' Name | args | ':' Name args
β = Name | '(' exp ')'

Rewritten rules:
prefixexp := ( Name | '(' exp ')' ) A'
A' := ( '[' exp ']' | '.' Name | args | ':' Name args ) A' | ε
```

--------------------------------

### Lua Table Construction Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch04-02

Demonstrates the construction of a Lua table supporting list, record, and general key-value pairs. This showcases different ways to initialize table elements.

```lua
local key = "kkk"
print { 100, 200, 300; -- list style
        x="hello", y="world"; -- record style
        [key]="vvv"; -- general style
}
```

--------------------------------

### Rust String Memory Layout Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates the memory layout of a Rust String, showing the metadata on the stack (buffer pointer, length, capacity) and the string content on the heap.

```text
__
    stack             heap
    +--------+
    | buffer +------->+----------------+
    |--------|        |hello, world!   |
    | len=13 |        +----------------+
    |--------|
    | cap=16 |
    +--------+


```

--------------------------------

### Lua Bytecode Instruction Explanations

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-02

Provides explanations for key Lua bytecode instructions used in the 'hello, world!' example. This includes VARARGPREP, GETTABUP, LOADK, CALL, and RETURN, detailing their purpose and parameters.

```plaintext
1. VARARGPREP, temporarily unused, ignored.
2. GETTABUP, this is a bit complicated, it can be temporarily understood as: loading global variables onto the stack. The three parameters are the stack index (0) as the target address, (ignore the second one,) and the index (0) of the global variable name in the constant table. The global variable name listed in the comments later is "print".
3. LOADK, load constants onto the stack. The two parameters are the stack index (1) as the destination address, and the constant index (1) as the loading source. The value of the constant listed in the comment below is "hello, world!".
4. CALL, function call. The three parameters are the stack index (0) of the function, the number of parameters, and the number of return values. The following comment indicates that there is 1 parameter and 0 return value.
5. RETURN, temporarily unused, ignored.

```

--------------------------------

### Lua Code Example with Function Call

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-01

A snippet illustrating a simple Lua program with a function definition and a subsequent call to that function.

```lua
local a, b = 1, 2
local function foo()
     local x, y = 1, 2
end
foo()
```

--------------------------------

### Lua Bytecode for Table Construction

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch04-02

Presents the bytecode generated by `luac` for the Lua table construction example. It highlights instructions like NEWTABLE, SETFIELD, and SETLIST.

```assembly
$ luac -l test_lua/table.lua

main <test_lua/table.lua:0,0> (14 instructions at 0x600001820080)
0+ params, 6 slots, 1 upvalue, 1 local, 7 constants, 0 functions
    1	[1]	VARARGPREP	0
    2	[1]	LOADK    	0 0	; "kkk"
    3	[2]	GETTABUP 	1 0 1	; _ENV "print"
    4	[2]	NEWTABLE 	2 3 3	; 3
    5	[2]	EXTRAARG 	0
    6	[2]	LOADI    	3 100
    7	[2]	LOADI    	4 200
    8	[2]	LOADI    	5 300
    9	[3]	SETFIELD 	2 2 3k	; "x" "hello"
    10	[3]	SETFIELD 	2 4 5k	; "y" "world"
    11	[4]	SETTABLE 	2 0 6k	; "vvv"
    12	[5]	SETLIST  	2 3 0
    13	[2]	CALL     	1 2 1	; 1 in 0 out
    14	[5]	RETURN   	1 1 1	; 0 out
```

--------------------------------

### Lua Example: Binary Operations and Type Coercion

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch05-03

Demonstrates various binary operations in Lua, showcasing how integers and floating-point numbers are handled. It includes examples of addition, subtraction, division, and bitwise right shift, illustrating Lua's automatic type coercion rules and potential errors when incompatible types are used.

```lua
g = 10
local a,b,c = 1.1, 2.0, 100

print(100+g) -- commutative, AddInt
print(a-1)
print(100/c) -- result is float
print(100>>b) -- 2.0 will be convert to int 2
print(100>>a) -- panic

```

--------------------------------

### Lua Bytecode Example: GETTABUP

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-06

This snippet shows an example of Lua bytecode for reading a global variable, specifically 'print'. It illustrates the GETTABUP instruction and its associated operands, highlighting the internal representation used by the Lua VM.

```lua
2 [1] GETTABUP 0 0 0 ; _ENV "print"
```

--------------------------------

### Lua Code: Addition Statement

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Example Lua code snippet demonstrating a simple addition operation between two local variables.

```lua
local a = 1
local b = 2
r = a + b
```

--------------------------------

### Lua Syntax Examples

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch02-03

Illustrates the evolution of Lua syntax parsing, showing initial support for function calls and local variables, and the subsequent addition of variable assignment statements.

```lua
Name String
Name ( exp )
localName = exp
Name = exp # add new
```

--------------------------------

### Lua repeat..until Example with Local Variable

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch06-04

A Lua code example demonstrating the use of a local variable within a `repeat..until` loop, where the variable is accessed in the `until` condition.

```lua
-- keep retrying until the request succeeds
repeat
     local ok = request_xxx()
until ok
```

--------------------------------

### Lua Function Definition and Local Variables

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates the declaration of a Lua function with parameters and local variables. This code snippet is used to illustrate the stack layout in the subsequent example.

```lua
__
local function foo(a, b)
     local x, y = 1, 2
end


```

--------------------------------

### Lua Comparison Example: Equality and Inequality

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch07-03

Demonstrates Lua's behavior with equality checks between different types and the exception thrown for inequality comparisons between incompatible types.

```lua
print (123 == 'hello') -- prints false
print (123 > 'hello') -- throw exception
```

--------------------------------

### Minimal Interpreter: Print Statement Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/index

This snippet demonstrates the implementation of a minimal interpreter capable of parsing and executing a 'print "hello, world!"' statement. It serves as the foundational framework for the interpreter, showcasing the complete process from parsing to execution.

```rust
fn main() {
    // Placeholder for minimal interpreter logic
    println!("// Implementation of print \"hello, world!\" statement");
}
```

--------------------------------

### Lua Code with Multiple Print Statements (Lua)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

An example of Lua code demonstrating the support for multiple 'print' statements. This highlights the need for potential optimization in handling repeated constants in the future.

```Lua
print "hello, world!"
print "hello, again..."

```

--------------------------------

### Lua Tail Call Examples

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-05

Demonstrates various Lua function call scenarios to illustrate what constitutes a tail call. These examples are crucial for understanding the conditions under which tail call optimization can be applied.

```lua
function f1(x)
     g(x) -- discard the return value of g(x) before f1() returns
end
function f2(x)
     return g(x) + 1 -- also execute +1
end
function f3(x)
     return x or g(x) -- also limit the return value of g(x) to 1
end
function f4(x)
     return (g(x)) -- also limit the return value of g(x) to 1
end
```

--------------------------------

### Interpreter Implementation Stages

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Outlines a phased approach for implementing an interpreter, starting with defining the bytecode, then developing the parsing process to generate it, and finally creating the execution process (virtual machine) to run it.

```text
           generate           execute
     parse -------> bytecode <------- virtual machine
```

--------------------------------

### Lua dynamic typing example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-03

Demonstrates Lua's dynamic typing where a variable can be reassigned to different types.

```lua
local n = 10
n = "hello" -- OK
```

--------------------------------

### Lua Bytecode Example: Add Operation

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates the bytecode generated for a simple addition operation in Lua, showing how operand-related bytecodes can be interspersed. This sequence is considered acceptable for this specific operation.

```lua
__
local a = -g1 + -g2

```

```text
constants: ['g1', 'g2']
byte_codes:
   GetGlobal(0, 0) # parse the first operand
   GetGlobal(1, 1) # parse the second operand
   Neg(2, 0)       # discharge the first operand
   Neg(3, 1)       # discharge the second operand
   Add(0, 2, 3)

```

--------------------------------

### Lua Local Variable Definition and Usage

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch02-02

Demonstrates the Lua syntax for defining a local variable 'a' and then printing its value. This serves as a simple example of local variable management in Lua.

```lua
local a = "hello, local!" -- define new local var 'a'
print(a) -- use 'a'
```

--------------------------------

### Rust Vec<String> Memory Layout Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates the memory layout of a Rust Vec containing Strings, highlighting how String metadata itself can be stored on the heap as part of the Vec's data.

```text
__
    stack             heap
    +--------+
    | buffer +------->+-------------+-------------+----
    |--------|        | buf|len|cap | buf|len|cap | ...
    | len=2  |        +--+----------+--+----------+----
    |--------|           |             V
    | cap=4  |           V             +----------------+
    +--------+        +--------+       |hello, world!   |
                      |print   |       +----------------+
                      +--------+


```

--------------------------------

### Counter Example using Rust Closures

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Provides a practical example of implementing a counter using Rust closures. The 'test_new_counter' function creates a mutable counter 'i' within a closure and pushes it onto the Lua state as a 'Value::RustClosure'.

```rust
fn test_new_counter(state: &mut ExeState) -> i32 {
     let mut i = 0_i32;
     let c = move |_: &mut ExeState| {
         i += 1;
         println!("counter: {i}");
         0
     };
     state.push(Value::RustClosure(Rc::new(RefCell::new(Box::new(c)))))
     1
}
```

--------------------------------

### C Language Logical Operation Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates a typical logical AND operation in C, showing how operands are converted to boolean types and the result is represented as an integer (1 for true).

```c
int i=10, j=11;
printf("%d\n", i && j); // output: 1

```

--------------------------------

### Rust: Bytecode for Upvalue Operations

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Defines new bytecode instructions for managing upvalues in the virtual machine. These include getting an upvalue, setting an upvalue from the stack, and setting an upvalue from a constant.

```rust
pub enum ByteCode {
     //upvalue
     Getupvalue(u8, u8), // Load upvalue onto the stack
     Setupvalue(u8, u8), // Assign value from the stack
     SetupvalueConst(u8, u8), // assign value from constant
}
```

--------------------------------

### Lua Assignment: Variable Swap Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch04-05

Illustrates a common Lua assignment scenario: swapping the values of two local variables using simultaneous assignment.

```lua
local a, b = 1, 2
a, b = b, a --swap 2 variables!!!
```

--------------------------------

### Lua Function with Table Initialization

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch04-02

An example of a Lua function that initializes a table within its scope. The analysis suggests this can be inefficient due to repeated table construction.

```lua
local function day_of_week(day)
     local days = {
         "Sunday"=0, "Monday"=1, "Tuesday"=2,
         "Wednesday"=3, "Thursday"=4, "Friday"=5,
         "Saturday"=6,
     }
     return days[day]
end
```

--------------------------------

### Lua Table Construction Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch04-03

A simple Lua code snippet demonstrating the construction of a table with a key-value pair. It shows the declaration of local variables 'k' and 'v' and their assignment as key and value within a table literal.

```lua
local k = 'kkk'
local v = 'vvv'
local t = { [k] = v }
```

--------------------------------

### Lua Dynamic Typing Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates Lua's dynamic typing where a variable can hold values of different types sequentially. This highlights that the type is associated with the value, not the variable itself.

```lua
__
local n = 10
n = "hello" -- OK

```

--------------------------------

### Lua goto example with a backward jump

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-03

This Lua code snippet demonstrates the use of the `goto` statement to jump backward to a label. It also shows how a closure with an upvalue can be created and called within the loop, and how the local variable's scope is managed.

```lua
::again::
     if c1 then -- false when the first execution reaches here
         c1() -- after assigning a value to c1 below, c1 is a closure that includes an upvalue
     end

     local i = 0
     c1 = function()
         i = i + 1 -- upvalue
         print(i)
     end
     go to again

```

--------------------------------

### Lua Logical and Relational Operations Examples

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates the usage of logical ('and', 'or') and relational operators ('>', '<') in Lua within conditional judgments and evaluation scenarios. This demonstrates how these operations are integrated into control flow and expression evaluation.

```Lua
-- logic operation
if a and b then -- conditional judgment
     print(t.k or 0) -- evaluate
end

-- Relational operations
if a > b then -- conditional judgment
     print(c > d) -- evaluate
end

-- Combination of logical operations and relational operations
if a > b and c < d then -- conditional judgment
     print (x > 0 and x or -x) -- evaluate
end

```

--------------------------------

### Lua Table Indexing Examples

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates the two primary ways to access table elements in Lua: using string keys with square brackets (`t["k"]`) and using dot notation for direct property access (`t.k`). The dot notation is a syntactic sugar for the former.

```lua
t["k"]
```

```lua
t.k
```

--------------------------------

### Lua: Example of Local Variable Definition and Usage

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch02-02

This Lua code demonstrates defining local variables, including assigning string literals and referencing other local variables. It also shows how to call the 'print' function with local variables and how to shadow a global variable ('print') with a local one. Finally, it illustrates calling a locally defined function using a string literal.

```lua
local a = "hello, local!" -- define a local by string
local b = a -- define a local by another local
print(b) -- print local variable
print(print) -- print global variable
local print = print --define a local by global variable with same name
print "I'm local-print!" -- call local function

```

--------------------------------

### Rust: Automatic String to Value Conversion Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates how to use the implemented `str_to_value` function (implicitly via `into()`) to convert a string variable `var` into a `Value` type. This replaces manual type selection, simplifying code and preventing errors.

```rust
self.add_const(str_to_value(var));
```

```rust
self.add_const(var.into());
```

--------------------------------

### Lua Code Example with Unicode

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch03-04

A simple Lua code snippet that prints a string containing Chinese characters. This example is used to demonstrate the 'garbled code' problem when the interpreter does not handle UTF-8 correctly.

```lua
print "你好"

```

--------------------------------

### Lua Return Value Scenarios (Examples)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-03

Illustrates the three primary scenarios for handling Lua function return values: as the last argument, in variable assignments, and in other contexts like table indexing or conditional checks.

```lua
print("hello: ", foo(1, 2)) -- last argument
local t = {1, 2, foo()} -- last list member
return a+b, foo() -- the last return value
```

```lua
local x, y = foo() -- take the first 2 actual parameters and assign them to x and y respectively
t.k, t.j = a, foo() -- take the first actual parameter and assign it to t.j
```

```lua
local x, y = foo(), b -- not the last expression, just take the first argument and assign it to x
t.k, t.j = foo(), b -- not the last expression, just take the first argument and assign it to t.k
if foo() then -- conditional judgment
   t[foo()] = foo() + f -- table index, and binary operands
end
```

```lua
print("no results")
foo(1, 2, 3)
```

--------------------------------

### Lua goto example with closure and upvalue

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

This Lua code demonstrates an escape from a `goto` loop using a closure with an upvalue. The closure `c1` increments a counter `i` each time it's called. The `goto again` statement creates a loop, and the closure allows interaction with the loop's state.

```lua
__
::again::
     if c1 then -- false when the first execution reaches here
         c1() -- after assigning a value to c1 below, c1 is a closure that includes an upvalue
     end

     local i = 0
     c1 = function()
         i = i + 1 -- upvalue
         print(i)
     end
     go to again


```

--------------------------------

### Rust VM: Executing `CallSet` Bytecode

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates the virtual machine's execution logic for `CallSet` bytecode, including calling the function, handling return values, and cleaning the stack.

```rust
ByteCode::CallSet(dst, func, narg) => {
     // Call functions
     let nret = self. call_function(func, narg);

     if nret == 0 { // no return value, set nil
         self. set_stack(dst, Value::Nil);
     } else {
         // use swap() to avoid clone()
         let iret = self.stack.len() - nret as usize;
         self.stack.swap(self.base+dst as usize, iret);
     }

     // Clean up the stack space occupied by the function call
     self.stack.truncate(self.base + func as usize + 1);
 }
```

--------------------------------

### Implement 'print' Function in Rust (Rust)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-04

Provides the implementation code for the 'print' function in Rust, showing how it accesses arguments from the interpreter's state (stack) and prints them. This is a basic example of a Rust function callable from Lua.

```Rust
fn lib_print(state: &mut ExeState) -> i32 {
     println!("{}", state.stack[state.base + 1]);
     0
}
```

--------------------------------

### Lua Logic and Relational Operations Examples

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch07-00

Demonstrates the usage of logical operators (and, or) and relational operators (>) in Lua for conditional judgments (if statements) and expression evaluation. Includes examples combining both types of operations.

```lua
-- logic operation
if a and b then -- conditional judgment
     print(t.k or 0) -- evaluate
end

-- Relational operations
if a > b then -- conditional judgment
     print(c > d) -- evaluate
end

-- Combination of logical operations and relational operations
if a > b and c < d then -- conditional judgment
     print (x > 0 and x or -x) -- evaluate
end
```

--------------------------------

### Virtual Machine Bytecode for Function Call

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates the virtual machine's bytecode handling for a function call (`ByteCode::Call`). It demonstrates how to retrieve a function from the stack and execute it if it's a Lua function.

```rust
    ByteCode::Call(func, _) => {
        let func = &self. stack[func as usize];
        if let Value::Function(f) = func {
            f(self);

```

--------------------------------

### Lua _ENV Conversion Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-06

This example demonstrates how Lua code with global variables is converted using the _ENV environment. It shows a global assignment 'g1 = g2' transformed into operations on the _ENV table, illustrating how global variables are treated as upvalues.

```lua
local _ENV = XXX -- predefined global variable table
return function (...)
     _ENV.g1 = _ENV.g2
end
```

--------------------------------

### General Compilation Process Diagram

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-01

Illustrates the fundamental steps in compiling source code into executable forms, including lexical analysis, syntax analysis, and semantic analysis, leading to intermediate code.

```text
            Lexical Analysis        Syntax Analysis       Semantic Analysis
Character Stream --------> Token Stream --------> Syntax Tree --------> Intermediate Code ...
```

--------------------------------

### Rust: Initializing `ExeState` and setting `_ENV` in the stack

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

This Rust code snippet shows the initialization of the `ExeState` in the virtual machine execution stage. It demonstrates how `_ENV` (the global variable table) is pushed onto the stack as the first parameter, fulfilling the promise made during parsing.

```rust
__
impl ExeState {
     pub fn new() -> Self {
         // global variable table
         let mut env = Table::new(0, 0);
         env.map.insert("print".into(), Value::RustFunction(lib_print));
         env.map.insert("type".into(), Value::RustFunction(lib_type));
         env.map.insert("ipairs".into(), Value::RustFunction(ipairs));
         env.map.insert("new_counter".into(), Value::RustFunction(test_new_counter));

         ExeState {
             // Push 2 values on the stack: the virtual function entry, and the global variable table _ENV
             stack: vec![Value::Nil, Value::Table(Rc::new(RefCell::new(env)))],
             base: 1, // for entry function
         }
     }

```

--------------------------------

### Rust static typing example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-03

Illustrates Rust's static typing where a variable's type is fixed and cannot be changed.

```rust
let mut n: i32 = 10;
n = "hello"; // !!! Wrong
```

--------------------------------

### Rust ParseProto Initialization with Parameters

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-02

Illustrates the `new` function for the `ParseProto` structure in Rust. It initializes `FuncProto` with variable argument status and parameter count, and sets up the `locals` field using the provided parameter list.

```rust
impl<'a, R: Read> ParseProto<'a, R> {
     // Add has_varargs and params two parameters
     fn new(lex: &'a mut Lex<R>, has_varargs: bool, params: Vec<String>) -> Self {
         ParseProto {
             fp: FuncProto {
                 has_varargs: has_varargs, // Whether to support variable parameters
                 nparam: params.len(), // number of parameters
                 constants: Vec::new(),
                 byte_codes: Vec::new(),
             },
             sp: 0,
             locals: params, // Initialize the locals field with the parameter list
             break_blocks: Vec::new(),
             continue_blocks: Vec::new(),
             gotos: Vec::new(),
             labels: Vec::new(),
             lex: lex,
         }
     }
}
```

--------------------------------

### Rust: Load Expression onto Stack

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

The `load_exp` function orchestrates the process of loading an expression. It first captures the current stack pointer, then calls `exp()` to get the `ExpDesc`, and finally calls `discharge()` to place the `ExpDesc` onto the stack at the saved position.

```rust
     fn load_exp(&mut self) {
         let sp0 = self.sp;
         let desc = self. exp();
         self. discharge(sp0, desc);
     }

```

--------------------------------

### Use Standard Input with `ParseProto` (Rust)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch03-03

Demonstrates using standard input (`std::io::stdin`) as the source for `ParseProto::load`, highlighting the flexibility gained from generic input handling.

```Rust
fn main() {
     let input = std::io::stdin(); // standard input
     let proto = parse::ParseProto::load(input);
     vm::ExeState::new().execute(&proto);
}
```

--------------------------------

### Lua Bytecode Output for 'hello, world!'

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

The bytecode generated by the Lua compiler (`luac`) for the 'hello, world!' program. This output is analyzed to understand Lua's instruction set.

```text
$ luac -l hello_world.lua

main <hello_world.lua:0,0> (5 instructions at 0x600000d78080)
0+ params, 2 slots, 1 upvalue, 0 locals, 2 constants, 0 functions
    1\t[1]\tVARARGPREP\t0
    2\t[1]\tGETTABUP \t0 0 0\t; _ENV "print"
    3\t[1]\tLOADK    \t1 1\t; "hello, world!"
    4\t[1]\tCALL     \t0 2 1\t; 1 in 0 out
    5\t[1]\tRETURN   \t0 1 1\t; 0 out

```

--------------------------------

### Counter Example Using Rust Closures (Rust)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-04

This Rust function, `test_new_counter`, demonstrates the practical use of Rust closures within the Lua integration. It creates a mutable counter `i`, defines a closure that increments `i` and prints it, and then pushes this closure onto the Lua state's stack wrapped in the necessary `Rc`, `RefCell`, and `Box` types.

```Rust
fn test_new_counter(state: &mut ExeState) -> i32 {
     let mut i = 0_i32;
     let c = move |_: &mut ExeState| {
         i += 1;
         println!("counter: {i}");
         0
     };
     state.push(Value::RustClosure(Rc::new(RefCell::new(Box::new(c)))));
     1
}
```

--------------------------------

### Asserting Block End in `if_stat` (Rust)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch06-01

Example of asserting the expected `Token::End` return value from the modified `block()` function within an `if_stat` implementation in Rust.

```rust
assert_eq!(self. block(), Token::End);
```

--------------------------------

### Lua Bytecode Output for 'hello, world!'

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-02

Demonstrates the bytecode generated by the Lua compiler (`luac`) for a simple 'hello, world!' program. This output serves as a reference for understanding the structure and meaning of individual bytecode instructions.

```plaintext
$ luac -l hello_world.lua

main <hello_world.lua:0,0> (5 instructions at 0x600000d78080)
0+ params, 2 slots, 1 upvalue, 0 locals, 2 constants, 0 functions
    1\t[1]\tVARARGPREP\t0
    2\t[1]\tGETTABUP \t0 0 0\t; _ENV "print"
    3\t[1]\tLOADK \t1 1\t; "hello, world!"
    4\t[1]\tCALL \t0 2 1\t; 1 in 0 out
    5\t[1]\tRETURN \t0 1 1\t; 0 out

```

--------------------------------

### Rust: Byte to Character Conversion in Lexer

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Example of byte-to-character conversion within the `read_char` function of a Rust lexer. This highlights a potential issue when dealing with non-ASCII characters.

```rust
fn read_char(&mut self) -> char {
     match self. input. next() {
         Some(Ok(ch)) => ch as char, // u8 -> char

```

--------------------------------

### Handle Return Bytecode in Rust VM

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

This Rust code snippet demonstrates how the 'Return' bytecode is handled within a virtual machine. It calculates the absolute return address and cleans up temporary variables on the stack to ensure correct return value placement.

```rust
     ByteCode::Return(iret, nret) => {
         // convert relative address to absolute address
         let iret = self.base + iret as usize;

         // clean up temporary variables to ensure that `nret`
         // at the top of the stack is the return value
         self.stack.truncate(iret + nret as usize);

         return nret as usize;
     }
     ByteCode::Return0 => {
         return 0;
     }
```

--------------------------------

### Lua Multiple Upvalues Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-01

Illustrates a Lua code snippet with multiple upvalues within a function, demonstrating how different local variables from the outer scope are referenced.

```lua
local a, b, c = 100, 200, 300
local function foo()
     print (c, b)
end
```

--------------------------------

### Initialize VM with 'print' (Rust)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-04

Implements the `new` function for `ExeState`, initializing the global variable table with the 'print' function. This prepares the VM for executing Lua programs that use standard library functions.

```rust
impl ExeState {
    pub fn new() -> Self {
        let mut globals = HashMap::new();
        globals.insert(String::from("print"), Value::Function(lib_print));

        ExeState {
            globals,
            stack: Vec::new(),
        }
    }
}
```

--------------------------------

### Lua Basic Upvalue Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-01

Demonstrates a simple Lua code snippet where a function references a local variable defined in its outer scope, illustrating the concept of upvalue.

```lua
local a = 1
local function foo()
     print(a) -- What type of variable is `a`? Local variable, or global variable?
end
```

--------------------------------

### Running the Lua Interpreter (Shell)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-04

Demonstrates how to compile and run a Lua script using the Rust implementation. It shows the command-line execution and the expected output, including the intermediate constant table and bytecode.

```shell
$ cargo r -q --test_lua/hello.lua
[src/parse.rs:39] &constants = [
     print,
     hello, world!,
]
[src/parse.rs:40] &byte_codes = [
     GetGlobal(
         0,
         0,
     ),
     LoadConst(
         1,
         1,
     ),
     Call(
         0,
     ),
]
hello world!

```

--------------------------------

### Lua Function with Tail Call

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-05

Demonstrates a Lua function `foo` that makes a tail call to another function `bar`. This is a basic example of a tail-recursive or tail-called structure.

```lua
function foo(a, b)
     return bar(a + b)
end
```

--------------------------------

### Lua Bytecode for Addition

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch05-02

Illustrates the generated bytecode sequence for a simple Lua addition statement, showing how bytecodes for operands can be interspersed.

```text
constants: ['g1', 'g2']
byte_codes:
   GetGlobal(0, 0) # parse the first operand
   GetGlobal(1, 1) # parse the second operand
   Neg(2, 0)       # discharge the first operand
   Neg(3, 1)       # discharge the second operand
   Add(0, 2, 3)
```

--------------------------------

### Virtual Machine Execution of VarArgs Bytecode (Fixed)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-02

Illustrates the virtual machine execution logic for the `ByteCode::VarArgs` instruction when a specific number of arguments (`want`) is required. It adjusts the stack based on the destination and the number of arguments needed.

```rust
     ByteCode::VarArgs(dst, want) => {
         self.stack.truncate(self.base + dst as usize);

         let len = varargs.len(); // actual number of arguments
         let want = want as usize; // need the number of arguments
```

--------------------------------

### Rust Virtual Machine Execution for Jump

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch06-03

Demonstrates the modification in the Rust virtual machine's execution logic to handle the Jump bytecode with signed integers for backward jumps.

```Rust
         // unconditional jump
         ByteCode::Jump(jmp) => {
             pc = (pc as isize + jmp as isize) as usize;
         }
```

--------------------------------

### C Logical AND Operation Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch07-02

This C code snippet demonstrates the behavior of the logical AND (&&) operator. It shows how the operator evaluates operands and returns a numerical representation of the boolean result (1 for true).

```c
int i=10, j=11;
printf("%d\n", i && j); // output: 1
```

--------------------------------

### Execute Jump Bytecode with Signed Offset

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

This Rust code demonstrates the virtual machine's execution of the `Jump` bytecode. It handles the jump by adding the signed offset (`jmp`) to the current program counter (`pc`), enabling backward jumps necessary for loop constructs.

```Rust
// unconditional jump
ByteCode::Jump(jmp) => {
    pc = (pc as isize + jmp as isize) as usize;
}
```

--------------------------------

### Lua 'break' Statement Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch06-03

This Lua code demonstrates the behavior of the 'break' statement within nested 'while' loops and 'if' blocks. It shows how 'break' exits the nearest enclosing loop.

```lua
while 123 do -- outer loop block, support `break`
     while true do -- middle-level loop block, support `break`
         a = a + 1
         if a < 10 then -- inner block, does not support `break`
             `break` -- `break` out of the `while true do` loop
         end
     end
end

```

--------------------------------

### Lua Bytecode for 'while' loop

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch06-03

Illustrates the bytecode sequence for a 'while' loop, including a test for the condition and a backward jump.

```Text
/-->  Test --\  `if` branch
|     ...    |
\---  Jump   |
        <----/ The end of the entire `while` statement
```

--------------------------------

### Lua Upvalue Example: Basic Scenario

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Demonstrates the fundamental concept of upvalue in Lua, where a function references a local variable defined in an outer scope. This highlights how variables are captured by inner functions.

```lua
__
local a = 1
local function foo()
     print(a) -- What type of variable is `a`? Local variable, or global variable?
end

```

--------------------------------

### Lua Stack Layout with Variable Arguments (Initial)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-02

Illustrates a conceptual initial stack layout when calling a Lua function with variable arguments. 'a' and 'b' are fixed arguments, and '3', '4', '5' are the variable arguments.

```text
|     |
+-----+
| foo |
+=====+ <-- base
|  1  |  \ 
+-----+
+ Fixed arguments, corresponding to `a` and `b`
|  2  |  /
+-----+
|  3  |  \ 
+-----+
|  4  |   + Variable arguments, corresponding to `...`
+-----+
|  5  |  /
+-----+
```

--------------------------------

### Lua `break` example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates the behavior of the `break` statement within nested `while` loops in Lua. It shows how `break` exits the nearest loop block, even when nested within conditional blocks.

```lua
while 123 do -- outer loop block, support `break`
     while true do -- middle-level loop block, support `break`
         a = a + 1
         if a < 10 then -- inner block, does not support `break`
             `break` -- `break` out of the `while true do` loop
         end
     end
end
```

--------------------------------

### Initializing ExeState with _ENV on the Stack in Rust

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch09-06

This Rust code shows the initialization of an 'ExeState' which is crucial for the virtual machine execution stage. It pushes '_ENV' onto the stack as the first parameter, ensuring its availability when executing Lua code.

```rust
impl ExeState {
     pub fn new() -> Self {
         // global variable table
         let mut env = Table::new(0, 0);
         env.map.insert("print".into(), Value::RustFunction(lib_print));
         env.map.insert("type".into(), Value::RustFunction(lib_type));
         env.map.insert("ipairs".into(), Value::RustFunction(ipairs));
         env.map.insert("new_counter".into(), Value::RustFunction(test_new_counter));

         ExeState {
             // Push 2 values on the stack: the virtual function entry, and the global variable table _ENV
             stack: vec![Value::Nil, Value::Table(Rc::new(RefCell::new(env)))],
             base: 1, // for entry function
         }
     }
}
```

--------------------------------

### Lua Function with Multiple Return Values

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-03

Example of a Lua function that returns multiple values of different types. This demonstrates the scenario where return values need to be placed sequentially on the stack.

```lua
local function foo() 
     local x, y = 1, 2
     return x, "Yes", g1+g2
end

```

--------------------------------

### Lua Execution Stack Diagram

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

A visual representation of the Lua execution stack during the 'hello, world!' program, showing the state after loading 'print' and the string constant.

```text
  +-----------------+
0 | print           | <- function
  +-----------------+
1 | "hello, world!" |
  +-----------------+
  |                 |

```

--------------------------------

### C Do..While with Variable Scope Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch06-04

Illustrates C's 'do..while' loop behavior, showing that a variable declared inside the block is out of scope for the 'while' condition, resulting in a compilation error.

```c
     do {
         bool ok = request_xx();
     } while (ok); // error: 'ok' undeclared
```

--------------------------------

### Rust: Handle `[` exp `]` `=` exp for Lua Table Construction

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

This Rust code snippet handles the construction of Lua tables with indexed assignment, like `[key] = value`. It details the process of loading the key and value onto the stack and generating the `SetTable` bytecode. It's part of a larger Lua compiler/interpreter written in Rust.

```Rust
     Token::SqurL => { // `[` exp `]` `=` exp
         nmap += 1;
         self. lex. next();

         self.load_exp(sp); // load key to the top of the stack
         self.lex.expect(Token::SqurR); // `]`
         self.lex.expect(Token::Assign); // `=`
         self.load_exp(sp + 1); // load value to the top of the stack

         self.byte_codes.push(ByteCode::SetTable(table, sp as u8, sp as u8 + 1));
     },
```

--------------------------------

### Implement Lua print() Function - Rust

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-04

Demonstrates how to implement the Lua `print()` function using the Rust API. It iterates through the arguments using `get_top()` and retrieves each argument using `get::<&Value>()` to print them.

```Rust
fn lib_print(state: &mut ExeState) -> i32 {
     for i in 1 ..= state. get_top() {
         if i != 1 {
             print!("\t");
         }
         print!("{}", state.get::<&Value>(i).to_string());
     }
     println!("");
     0
}
```

--------------------------------

### Rust Static Typing Example

Source: https://wubingzheng.github.io/build-lua-in-rust/en/print

Illustrates Rust's static typing, where a variable is declared with a specific type (i32) and cannot be reassigned to a value of a different type (string). This shows that the type is bound to the variable.

```rust
__
let mut n: i32 = 10;
n = "hello"; // !!! Wrong

```

--------------------------------

### Lua Syntax for Variable Arguments Assignment

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-02

Demonstrates Lua syntax for assigning variable arguments to local variables and table fields. It illustrates how the `...` notation is used to capture arguments.

```lua
     local x, y = ... -- Take the first 2 arguments and assign them to x and y respectively
     t.k, t.j = a, ... -- Take the first argument and assign it to t.j
```

--------------------------------

### Lua Function with a Single Return Value (Local Variable)

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch08-03

Example of a Lua function returning a single local variable. This highlights the optimization where existing stack variables don't need to be re-pushed.

```lua
local function foo() 
     local x, y = 1, 2
     return x
end

```

--------------------------------

### Execute Lua 'hello, world!' in Rust Interpreter

Source: https://wubingzheng.github.io/build-lua-in-rust/en/ch01-00

This snippet demonstrates the target Lua code that the Rust interpreter will execute. It showcases basic Lua syntax including a standard library function call and a string literal.

```lua
print "hello, world!"
```
Tokens:
Raw