Lua Parser

Common errors

• UnicodeDecodeError: 'charmap' codec can't decode byte 0x93 in position 123: character maps to <undefined>

  cause Attempting to parse a Lua file that is not UTF-8 encoded after upgrading to luaparser >= 4.0.0. The parser now defaults to UTF-8.
  fix Ensure your Lua source files are saved in UTF-8. If not possible, read the file with the correct encoding explicitly and pass the string content to `parse()`.

• AttributeError: 'Name' object has no attribute 'value' (or 'String' object has no attribute 'id')

  cause This error occurs when code expects `Index.idx` to be a `String` node (with `.value`) but it's a `Name` node (with `.id`) in luaparser >= 3.0.0, or vice-versa if trying to access `.id` on an old `String` node.
  fix Update your AST traversal to correctly handle the type of `Index.idx`. For `luaparser >= 3.0.0`, if `isinstance(idx_node, luaparser.ast.Name)`, use `idx_node.id`. If `isinstance(idx_node, luaparser.ast.String)`, use `idx_node.raw` (for 4.0.0+) or `idx_node.value` (for 3.x).

• luaparser.errors.ParseError: Unknown token at line X, column Y: '?'

  cause After upgrading to luaparser >= 4.0.0, the parser is stricter and does not skip unknown tokens, leading to an immediate error for invalid Lua syntax that might have been tolerated in older versions.
  fix Examine the Lua code at the specified line and column for any syntax errors or non-standard constructs. Ensure it strictly conforms to Lua grammar.

Warnings

• breaking Source file encoding changed from local encoding to UTF-8. Parsing files with non-UTF-8 encodings will now raise a `UnicodeDecodeError` by default.
  Fix: Ensure all Lua source files are saved with UTF-8 encoding. If not possible, pre-read the file with its correct encoding and pass the string to `parse()`.
• breaking The `String` AST node's internal representation for string values changed. The `s` attribute now stores bytes, and a new `raw` attribute stores the unescaped string. Code directly accessing `s` for string content may break.
  Fix: Access the `raw` attribute of `String` nodes for the unescaped string value. Example: `string_node.raw`.
• breaking The parser is now stricter: it fails immediately on an unknown token instead of attempting to skip it. This means previously 'tolerated' invalid Lua code will now raise a `ParseError`.
  Fix: Review Lua code for strict grammar compliance. The `ParseError` message should indicate the location of the offending token.
• breaking The `Index.idx` attribute type changed from a `String` node to a `Name` node. Code expecting `Index.idx` to have a `.value` attribute for the index string will break.
  Fix: Update AST traversal logic to check the type of `Index.idx`. If it's a `Name` node, access `Index.idx.id` for the index name. If it's a `String` node (for older versions or specific cases), use `Index.idx.raw` (for 4.0.0+) or `Index.idx.value` (for 3.x).
• gotcha The `parse()` function no longer prints the AST directly to `stdout` upon execution. Users must explicitly call `ast.show()` or `print(ast.show())` to visualize the parsed tree.
  Fix: After parsing, call `print(ast.show())` to see the AST representation.

Install

• pip install luaparser Install luaparser

Imports

• parse

  from luaparser import parse

• Node

  from luaparser.ast import Node

Quickstart

Parses a simple Lua script string and prints its Abstract Syntax Tree (AST) representation to the console.

from luaparser import parse

lua_code = """
-- This is a simple Lua script
local function greet(name)
    print("Hello, " .. name .. "!")
end

greet("World")
"""

# Parse the Lua code into an AST
ast = parse(lua_code)

# Print a representation of the AST
# In luaparser 3.3.1+, parse() no longer prints directly
print(ast.show())