Unluac

https://github.com/x3zvawq/unluac-rs
Admin
Multi-dialect Lua decompiler written in Rust that reconstructs source code from compiled Lua...
Tokens:5,187
Snippets:60
Trust Score:9
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Rust Dependency Setup (Git)

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Use this in your Cargo.toml to include the latest unreleased changes from the main branch.

```toml
[dependencies]
unluac = { git = "https://github.com/x3zvawq/unluac-rs" }
```

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

### Install unluac-cli with Cargo

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Install the unluac-cli package from a local checkout using Cargo.

```bash
cargo install --path packages/unluac-cli
```

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

### Rust Dependency Setup (Crates.io)

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Add this to your Cargo.toml to use the released version of the unluac Rust crate.

```toml
[dependencies]
unluac = "1"
```

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

### Minimal Rust Decompilation Example

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Reads a Lua bytecode file, decompiles it to Lua 5.1 source, and prints the generated source. Ensure 'sample.out' exists in the same directory.

```rust
use std::fs;

use unluac::decompile::{decompile, DecompileDialect, DecompileOptions, DecompileStage};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let bytes = fs::read("sample.out")?;

    let result = decompile(
        &bytes,
        DecompileOptions {
            dialect: DecompileDialect::Lua51,
            target_stage: DecompileStage::Generate,
            ..DecompileOptions::default()
        },
    )?;

    if let Some(generated) = result.state.generated.as_ref() {
        println!("{}", generated.source);
    }

    Ok(())
}
```

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

### Install unluac-js

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Install the unluac-js package using npm. Ensure Node.js version 18 or higher is used for Node.js environments.

```bash
npm install unluac-js
```

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

### Minimal Node.js Decompilation Example

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Reads a Lua bytecode file using Node.js promises API, decompiles it to Lua 5.1 source, and prints the result. Ensure 'sample.luac' exists.

```js
import { decompile } from "unluac-js";
import { readFile } from "node:fs/promises";

const chunkBytes = await readFile("./sample.luac");
const source = await decompile(chunkBytes, {
  dialect: "lua5.1",
});

console.log(source);
```

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

### Node.js Decompile Example

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Decompile a Lua chunk in Node.js using the decompile function and log supported dialect values. Reads chunk bytes from a file.

```js
import { decompile, supportedOptionValues } from "unluac-js";
import { readFile } from "node:fs/promises";

const chunkBytes = await readFile("./sample.luac");

const values = await supportedOptionValues();
console.log(values.dialects);

const source = await decompile(chunkBytes, {
  dialect: "lua5.1",
});

console.log(source);
```

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

### Initialize Lua Toolchain Management

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Run this command to set up the necessary configurations for managing Lua toolchains.

```bash
cargo lua init
```

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

### List Available Lua Toolchains

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Use this command to see all the Lua toolchains available for management.

```bash
cargo lua list
```

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

### Fetch All Lua Toolchains

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Downloads the source code for all configured Lua toolchains. This is a prerequisite for building.

```bash
cargo lua fetch all
```

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

### Build Lua 5.1 Toolchain

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Compiles the Lua 5.1 toolchain. Ensure all host prerequisites are met before building.

```bash
cargo lua build lua5.1
```

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

### Browser Initialize and Decompile

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Initialize the wasm module and decompile a Lua chunk in a browser environment using a bundler. Assumes the bundler resolves wasm assets automatically.

```ts
import { decompile, init } from "unluac-js";

await init();

const source = await decompile(chunkBytes, {
  dialect: "luau",
});

console.log(source);
```

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

### Build LuaJIT Toolchain

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Compiles the LuaJIT toolchain. This includes its bundled modules and a compatibility wrapper.

```bash
cargo lua build luajit
```

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

### Run unluac-cli from local checkout

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Execute the unluac-cli tool directly from the repository during development.

```bash
cargo run -p unluac-cli -- --help
```

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

### Build Luau Toolchain

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Compiles the Luau toolchain, which includes analysis and compilation utilities.

```bash
cargo lua build luau
```

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

### init

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Initializes the wasm module explicitly. This can be called to prepare the module before performing any decompilation tasks. In Node.js, it automatically reads the packaged wasm file. In the browser, it can accept a URL to the wasm asset.

```APIDOC
## init(input?)

### Description
Initializes the WebAssembly module for unluac. This function can be called explicitly to ensure the wasm module is ready before use. It can optionally accept a URL or path to the wasm file, particularly useful in browser environments or specific Node.js setups.

### Method
`init(input?: string | URL)`

### Parameters
#### Path Parameters
- `input` (string | URL) - Optional - The path or URL to the wasm file. If not provided, the package attempts to locate the default wasm asset.

### Usage Example (Node.js)
```js
import { init } from "unluac-js";

await init();
```

### Usage Example (Browser)
```ts
import { init } from "unluac-js";

// Using default asset resolution
await init();

// Explicitly providing wasm location
await init(new URL("./unluac_wasm_bg.wasm", import.meta.url));
```
```

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

### Browser Initialize with Explicit Wasm URL

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Initialize the wasm module in the browser by providing the explicit URL to the wasm file. This is useful if automatic asset resolution is not configured.

```ts
import { decompile, init } from "unluac-js";

await init(new URL("./unluac_wasm_bg.wasm", import.meta.url));

const source = await decompile(chunkBytes, {
  dialect: "lua5.4",
});

console.log(source);
```

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

### Decompile chunk and output to file

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Decompile a Lua chunk and save the generated Lua source to a specified output file.

```bash
unluac-cli -i /absolute/path/to/chunk.out -D lua5.1 -o /tmp/case.lua
```

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

### Node.js Initialize Explicitly

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Explicitly initialize the wasm module in Node.js. This can be called early in your application's startup path.

```js
import { init } from "unluac-js";

await init();
```

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

### supportedOptionValues

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Retrieves the currently supported enum-like values for various decompilation options, allowing users to inspect available settings.

```APIDOC
## supportedOptionValues()

### Description
Returns an object containing the currently supported enum-like values for various decompilation options. This function is useful for inspecting the available choices for parameters like `dialect`, `parseModes`, `stringEncodings`, etc., before calling `decompile` or `decompileRich`.

### Method
`supportedOptionValues(): Promise<SupportedOptionValues>`

### Parameters
None.

### Request Example
```js
import { supportedOptionValues } from "unluac-js";

const values = await supportedOptionValues();
console.log(values.dialects);
console.log(values.namingModes);
```

### Response
#### Success Response (200)
- `dialects` (Array<string>) - Supported Lua dialects.
- `parseModes` (Array<string>) - Supported parsing modes.
- `stringEncodings` (Array<string>) - Supported string encodings.
- `stringDecodeModes` (Array<string>) - Supported string decoding modes.
- `namingModes` (Array<string>) - Supported identifier naming modes.
- `generateModes` (Array<string>) - Supported code generation modes.
- `quoteStyles` (Array<string>) - Supported quote styles for strings.
- `tableStyles` (Array<string>) - Supported table formatting styles.
```

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

### Decompile Lua source with specified dialect

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Decompile a Lua source file using unluac-cli. This involves an external compilation step before decompilation.

```bash
unluac-cli -s tests/unit-case/lua51_01.lua -D lua5.1
```

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

### Decompile chunk with specified dialect

Source: https://github.com/x3zvawq/unluac-rs/blob/main/README.md

Decompile a Lua chunk file using the unluac-cli, specifying the input file and Lua dialect.

```bash
unluac-cli -i /absolute/path/to/chunk.out -D lua5.1
```

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

### Clean Lua 5.1 Toolchain Build Artifacts

Source: https://github.com/x3zvawq/unluac-rs/blob/main/lua/README.md

Removes the build artifacts for the Lua 5.1 toolchain, freeing up disk space or preparing for a fresh build.

```bash
cargo lua clean lua5.1
```

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

### decompile

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Decompiles a compiled Lua chunk into its original source string. It accepts raw bytes and optional configuration options to control the decompilation process, such as the Lua dialect.

```APIDOC
## decompile(bytes, options?)

### Description
Decompiles a compiled Lua bytecode chunk and returns the final generated Lua source string. This is the primary function for obtaining the readable source code from binary Lua chunks.

### Method
`decompile(bytes: BufferSource | ArrayLike<number>, options?: DecompileOptions): Promise<string>`

### Parameters
#### Path Parameters
- `bytes` (BufferSource | ArrayLike<number>) - Required - The compiled Lua bytecode as a buffer or array-like object of numbers.

#### Query Parameters
- `options` (DecompileOptions) - Optional - An object containing options to customize the decompilation process.
  - `dialect` (string) - Specifies the Lua dialect (e.g., "lua5.1", "luau").
  - `parse` (ParseMode) - Controls how the bytecode is parsed.
  - `readability` (ReadabilityMode) - Adjusts the output source code's readability.
  - `naming` (NamingMode) - Determines how identifiers are named.
  - `generate` (GenerateMode) - Controls the code generation process.

### Request Example
```js
import { decompile } from "unluac-js";
import { readFile } from "node:fs/promises";

const chunkBytes = await readFile("./sample.luac");
const source = await decompile(chunkBytes, {
  dialect: "lua5.1",
});
console.log(source);
```

### Response
#### Success Response (200)
- `source` (string) - The decompiled Lua source code.
```

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

### decompileRich

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Decompiles a Lua chunk and returns a structured analysis result, including the source code, warnings, proto metadata, and control flow graphs.

```APIDOC
## decompileRich(bytes, options?)

### Description
Decompiles a compiled Lua bytecode chunk and returns a detailed, structured analysis result. This includes the generated Lua source, any warnings encountered during generation, metadata about function prototypes, and control flow graph (CFG) data.

### Method
`decompileRich(bytes: BufferSource | ArrayLike<number>, options?: DecompileOptions): Promise<DecompileRichResult>`

### Parameters
#### Path Parameters
- `bytes` (BufferSource | ArrayLike<number>) - Required - The compiled Lua bytecode as a buffer or array-like object of numbers.

#### Query Parameters
- `options` (DecompileOptions) - Optional - An object containing options to customize the decompilation process. Supported options include `dialect`, `parse`, `readability`, `naming`, and `generate`.

### Request Example
```ts
import { decompileRich } from "unluac-js";

const result = await decompileRich(chunkBytes, { dialect: "luau" });

console.log(result.source);
console.log(result.warnings);
console.log(result.protos);
console.log(result.cfgs);
```

### Response
#### Success Response (200)
- `source` (string) - The decompiled Lua source code.
- `warnings` (Array<string>) - An array of warnings generated during the decompilation process.
- `protos` (Array<UnluacProtoMeta>) - An array of objects containing metadata for each function prototype (name, line range, parameters, upvalues, constants, instructions, children).
- `cfgs` (Array<UnluacProtoCfg>) - An array of objects containing control flow graph data for each prototype (blocks with Low-IR and bytecode instructions, edges with type labels).
```

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

### Decompile Rich Analysis Result

Source: https://github.com/x3zvawq/unluac-rs/blob/main/packages/unluac-js/README.md

Decompile Lua bytecode and obtain a structured analysis result including source, warnings, proto metadata, and control flow graphs. Uses the decompileRich function.

```ts
import { decompileRich } from "unluac-js";

const result = await decompileRich(chunkBytes, { dialect: "lua5.1" });

console.log(result.source);    // final Lua source
console.log(result.warnings);  // generation warnings
console.log(result.protos);    // proto metadata (DFS order)
console.log(result.cfgs);      // per-proto CFG with blocks and edges
```
Tokens:
Raw