Pkg.LUAC — API for parsing Lua compiled bytecode files

Overview

The Pkg.LUAC module contains the API for parsing Lua compiled bytecode (LUAC) files. It supports all major Lua versions from 5.0 through 5.4, including version-specific opcode sets, instruction encoding, and constant types.

Disassembling a LUAC File

The following code example demonstrates how to disassemble a Lua bytecode file:

from Pro.Core import *
from Pkg.LUAC import *

def disassembleLUAC(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = LUACObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    out = NTTextBuffer()
    obj.Disassemble(out)
    print(out.buffer)

Inspecting Function Prototypes

The following code example demonstrates how to inspect the parsed function tree:

from Pro.Core import *
from Pkg.LUAC import *

def inspectLUAC(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = LUACObject()
    if not obj.Load(c) or not obj.Initialize():
        return
    v = obj.GetVersion()
    print("Lua version: %d.%d" % v)
    func = obj.GetFunction()
    print("source:", func.source)
    print("instructions:", len(func.instructions))
    print("constants:", len(func.constants))
    print("child functions:", len(func.protos))
    print("opcodes:", obj.GetOpcodes())

Module API

Pkg.LUAC module API.

Classes:

LUACObject()

This class represents a Lua compiled bytecode (LUAC) file.

LuaFunction()

This class holds the parsed data of a single Lua function prototype.
class LUACObject

Bases: Pro.Core.CFFObject

This class represents a Lua compiled bytecode (LUAC) file.

Methods:

DecodeInstruction(raw)

Decodes a raw 32-bit instruction word into its component fields.

Disassemble(out, *[, wo])

Disassembles the entire LUAC file to a human-readable form.

DisassembleFunction(out, func, *[, wo])

Disassembles a single function prototype.

DumpHeader(out)

Dumps the LUAC file header information to a text stream.

GetEndOffset()

Returns the offset immediately after the last byte consumed by the parser.

GetFunction()

Returns the top-level function prototype parsed from the file.

GetHeaderSize()

Returns the size of the LUAC file header in bytes.

GetOpModes()

Returns a dictionary mapping opcodes (as integers) to their instruction format type (as integers).

GetOpcodes()

Returns a dictionary mapping opcodes (as integers) to their corresponding mnemonics (as strings).

GetSourceName()

Returns the source file name embedded in the LUAC file, if available.

GetVersion()

Returns the Lua major and minor version of the LUAC file as a tuple.

Parse(*[, wo])

Parses the LUAC file.
DecodeInstruction(raw: int) → Tuple[int, int, int, int, int, int, int, int, int]

Decodes a raw 32-bit instruction word into its component fields.

The decoding is version-aware:

  • Lua 5.0–5.3: 6-bit opcode, 8-bit A, 9-bit B, 9-bit C, 18-bit Bx/sBx, 26-bit Ax.

  • Lua 5.4: 7-bit opcode, 8-bit A, 8-bit B, 8-bit C, 1-bit k, 17-bit Bx/sBx, 25-bit Ax/sJ.

Which fields are meaningful depends on the instruction format (see GetOpModes()):

  • OP_iABC: use op, a, b, c (and k for Lua 5.4).

  • OP_iABx: use op, a, bx.

  • OP_iAsBx: use op, a, sbx.

  • OP_iAx: use op, ax.

  • OP_isJ: use op, sj.

For Lua 5.0–5.3 OP_iABC instructions, operands B and C are 9 bits wide. If bit 8 is set (i.e. operand >= 256), the lower 8 bits (operand & 0xFF) index the constant pool rather than a register.

Parameters

raw (int) – The raw 32-bit instruction word from LuaFunction.instructions.

Returns

Returns a tuple (op, a, b, c, bx, sbx, ax, k, sj).

Return type

Tuple[int, int, int, int, int, int, int, int, int]

See also GetOpcodes(), GetOpModes().

Disassemble(out: Pro.Core.NTTextStream, *, wo: Optional[Pro.Core.NTIWait] = None) → None

Disassembles the entire LUAC file to a human-readable form.

Parameters

  • out (NTTextStream) – The output text stream.

  • wo (Optional[NTIWait]) – Optional wait object for long-running operations.

See also DisassembleFunction().

DisassembleFunction(out: Pro.Core.NTTextStream, func: Pkg.LUAC.LuaFunction, *, wo: Optional[Pro.Core.NTIWait] = None) → None

Disassembles a single function prototype.

Parameters

  • out (NTTextStream) – The output text stream.

  • func (LuaFunction) – The function prototype to disassemble.

  • wo (Optional[NTIWait]) – Optional wait object for long-running operations.

See also Disassemble(), GetFunction().

DumpHeader(out: Pro.Core.NTTextStream) → None

Dumps the LUAC file header information to a text stream.

Parameters

out (NTTextStream) – The output text stream.

GetEndOffset() → int

Returns the offset immediately after the last byte consumed by the parser.

Returns

Returns the end offset.

Return type

int

GetFunction() → Optional[Pkg.LUAC.LuaFunction]

Returns the top-level function prototype parsed from the file.

Returns

Returns the root LuaFunction if parsing succeeded; otherwise returns None.

Return type

Optional[LuaFunction]

See also Parse().

GetHeaderSize() → int

Returns the size of the LUAC file header in bytes.

Returns

Returns the header size.

Return type

int

GetOpModes() → Dict[int, int]

Returns a dictionary mapping opcodes (as integers) to their instruction format type (as integers).

The format types are defined in Pkg.LUAC.Opcodes:

  • OP_iABC (0) – three operands: A, B, C.

  • OP_iABx (1) – operand A and unsigned extended operand Bx.

  • OP_iAsBx (2) – operand A and signed extended operand sBx.

  • OP_iAx (3) – single large unsigned operand Ax (Lua 5.2+).

  • OP_isJ (4) – single large signed jump operand sJ (Lua 5.4+).

Returns

Returns the opcode mode dictionary.

Return type

Dict[int, int]

See also GetOpcodes(), DecodeInstruction().

GetOpcodes() → Dict[int, str]

Returns a dictionary mapping opcodes (as integers) to their corresponding mnemonics (as strings).

The opcode set depends on the Lua version of the file.

Returns

Returns the opcode dictionary.

Return type

Dict[int, str]

GetSourceName() → Optional[str]

Returns the source file name embedded in the LUAC file, if available.

Returns

Returns the source name string or None.

Return type

Optional[str]

GetVersion() → Tuple[int, int]

Returns the Lua major and minor version of the LUAC file as a tuple.

Returns

Returns a tuple (major, minor), e.g. (5, 4).

Return type

Tuple[int, int]

Parse(*, wo: Optional[Pro.Core.NTIWait] = None) → bool

Parses the LUAC file.

Parameters

wo (Optional[NTIWait]) – Optional wait object for long-running operations.

Returns

Returns True if successful; otherwise returns False.

Return type

bool

See also GetFunction(), Disassemble().

class LuaFunction

This class holds the parsed data of a single Lua function prototype.

Attributes:

abslineinfo

The list of absolute line info entries as (pc, line) tuples (Lua 5.4 only).

constants

The list of constants as (type_tag, value) tuples.

instructions

The list of raw 32-bit instruction words.

is_vararg

Whether this function accepts a variable number of arguments.

last_line_defined

The last line number where this function is defined.

line_defined

The first line number where this function is defined.

lineinfo

The list of line numbers, one per instruction.

locvars

The list of local variable debug entries as (name, startpc, endpc) tuples.

max_stack_size

The number of registers (stack slots) used by this function.

num_params

The number of fixed parameters.

num_upvalues

The number of upvalues used by this function.

protos

The list of child function prototypes.

source

The source file name, if available.

upvalue_names

The list of upvalue debug names.

upvalues

The list of upvalue descriptors.
abslineinfo: List[Tuple[int, int]]

The list of absolute line info entries as (pc, line) tuples (Lua 5.4 only).

constants: List[Tuple[int, Optional[Union[int, float, bool, bytes, str]]]]

The list of constants as (type_tag, value) tuples.

instructions: List[int]

The list of raw 32-bit instruction words.

is_vararg: int

Whether this function accepts a variable number of arguments.

last_line_defined: int

The last line number where this function is defined.

line_defined: int

The first line number where this function is defined.

lineinfo: List[int]

The list of line numbers, one per instruction.

locvars: List[Tuple[Optional[str], int, int]]

The list of local variable debug entries as (name, startpc, endpc) tuples.

max_stack_size: int

The number of registers (stack slots) used by this function.

num_params: int

The number of fixed parameters.

num_upvalues: int

The number of upvalues used by this function.

protos: List[Pkg.LUAC.LuaFunction]

The list of child function prototypes.

source: Optional[str]

The source file name, if available.

upvalue_names: List[Optional[str]]

The list of upvalue debug names.

upvalues: List[Any]

The list of upvalue descriptors. For Lua 5.2+ these are (instack, idx) tuples.