luaparse

library0.3.1jsnpmunverified

luaparse is a JavaScript-based Lua parser that generates an Abstract Syntax Tree (AST) from Lua source code. Originally developed by Oskar Schöldström for his bachelor's thesis, it supports various Lua versions including '5.1', '5.2', '5.3', and 'LuaJIT'. The current stable version is 0.3.1, primarily a maintenance release addressing issues from 0.3.0. The library offers flexible parsing options, allowing control over comment storage, scope tracking, location and range information, and custom node/scope creation callbacks. It can be used in CommonJS environments, AMD, and directly in browsers via a global `luaparse` object. A key differentiator is its detailed configuration for handling different Lua versions and its comprehensive AST output, including specific options for character encoding interpretation due to the difference between JavaScript's Unicode strings and Lua's bytestrings.

serialization

npm install luaparse

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · LUAPARSE

luaparse

serializationjavascriptv0.3.1

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parser

✓ var parser = require('luaparse');

✗ import parser from 'luaparse';

The library primarily targets CommonJS and global browser environments, with no official ESM support documented.

luaparse

✓ var ast = luaparse.parse('i = 0');

✗ import { parse } from 'luaparse';

When included directly in a browser via a script tag, `luaparse` becomes a global object. For CommonJS, `require('luaparse')` assigns the parser object.

luaparse.defaultOptions

✓ luaparse.defaultOptions.comments = true;

✗ parser.defaultOptions.comments = true; // if parser is named differently

Global default options are exposed directly on the `luaparse` object.

Parses a simple Lua script, including comments and location data, and logs the resulting AST. Also demonstrates accessing node properties.

const luaparse = require('luaparse'); const luaCode = ` -- This is a simple Lua script local function greet(name) print("Hello, " .. name .. "!") end greet("World") i = 0 while i < 3 do i = i + 1 end `; const ast = luaparse.parse(luaCode, { comments: true, // Store comments in the AST locations: true, // Store location information for each node luaVersion: '5.3' // Target Lua 5.3 grammar }); console.log(JSON.stringify(ast, null, 2)); // Example of accessing a specific node type (StringLiteral value change in v0.3.0) const firstStringLiteral = ast.body[0].body[0].args[0].value; console.log(`First string literal value: ${firstStringLiteral}`);

Debug

Known issues

breakingString literal nodes in the AST no longer contain the raw, unescaped contents by default since v0.3.0/v0.3.1. The `value` property on `StringLiteral` nodes will be `null` if `encodingMode` is `'none'` (the default).

fix

To retrieve the actual string content, you need to explicitly set `encodingMode` to a value like `'x-user-defined'` or `'pseudo-latin1'` in the options passed to `luaparse.parse()`. Alternatively, for the raw string including quotes, use the `raw` property if available and not null.

affects: >=0.3.0

gotchaThe `extendedIdentifiers: false` option, which controls whether code points ≥ U+0080 are allowed in identifiers, is *not* automatically enabled when `luaVersion` is set to `'LuaJIT'`. It must be explicitly enabled.

fix

If you require extended identifiers for LuaJIT syntax, you must explicitly pass `extendedIdentifiers: true` in the options object to `luaparse.parse()` in addition to `luaVersion: 'LuaJIT'`.

affects: >=0.1.0

gotchaThe default `encodingMode` is `'none'`, which means source code characters pass through as-is, and string literals are not interpreted, resulting in the `value` property of `StringLiteral` nodes being `null`. This can lead to unexpected behavior if expecting processed string values.

fix

To correctly interpret string literal values, particularly those with non-ASCII characters or escape sequences, set `encodingMode` to `'x-user-defined'` or `'pseudo-latin1'` in the parser options.

affects: >=0.3.0

gotchaThe library lacks official ESM support and is primarily designed for CommonJS (`require()`) and global browser environments. Direct `import` statements may not work without a CommonJS-to-ESM wrapper or bundler configuration.

fix

For Node.js, use `const luaparse = require('luaparse');`. For browsers, include via a `<script>` tag and access the global `luaparse` object.

affects: All versions

gotchaThe project's npm package shows a last publish date of June 2021 for v0.3.1, and there are open issues regarding maintenance status and unicode handling. While functional, ongoing active development might be limited.

fix

Be aware that new features or fixes for complex parsing issues might not be actively developed. Consider reviewing the open issues on GitHub for known limitations.

affects: All versions

Errors

Common errors & fixes

ReferenceError: luaparse is not defined

Attempting to use `luaparse.parse()` in a Node.js ESM context or without correctly assigning the `require()` result to a variable.

fix

Ensure you are using `const luaparse = require('luaparse');` for CommonJS modules, or that the library is correctly loaded as a global script in a browser environment.

TypeError: Cannot read properties of null (reading 'value') on StringLiteral nodes

By default, `luaparse` does not interpret string literal values, especially after v0.3.0, setting the `value` property to `null` if `encodingMode` is `'none'`.

fix

Pass `encodingMode: 'x-user-defined'` or `encodingMode: 'pseudo-latin1'` in the options object to `luaparse.parse()` to get processed string values. Alternatively, inspect the `raw` property for the original string literal including quotes.

SyntaxError: Unexpected token <token_name> (or similar parsing errors when using `wait: true`)

When using the streaming API with `wait: true`, the parser expects `parser.end()` to be called to finalize parsing after all `parser.write()` calls. Failure to do so leaves the input stream open.

fix

Always invoke `parser.end(remainingInput)` after `parser.write()` calls to signal the end of the input stream and retrieve the final AST.

Upgrade

Version history

0.3.1latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

4 hits · last 30 days

node

Resources

githubhttps://github.com/fstirlitz/luaparse ↗

packagehttps://www.npmjs.com/package/luaparse ↗

homepagehttps://fstirlitz.github.io/luaparse/ ↗