You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: split the reference out of the README into docs/
The README was 353 lines, 219 of them a single API code block. That block was
also the worst part of it: one continuous listing of JSDoc comments, which
cannot be linked to, scanned, or read on a phone.
Splits it into docs/ and rewrites the reference as real prose with per-method
sections, grouped by what you are trying to do rather than by declaration order.
Adds the type-conversion tables and the stack-index rules, which were previously
only discoverable by reading the tests.
docs/api.md full reference, with its own table of contents
docs/migrating-to-2.0.md the breaking-changes table and what to check
docs/troubleshooting.md build failures, including the Windows node-gyp and
npm-12-blocks-scripts cases users will actually hit
docs/development.md layout, CI, and the release process
README keeps what someone needs to decide whether to use this and get it
running: what it is, install, quick start, links, caveats. Now 100 lines with a
table of contents.
Documentation links are absolute GitHub URLs so they also work when the README
is rendered on npmjs.com, where relative links break. docs/ is not in the files
allowlist, so the tarball does not grow.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2.0.0 is a maintenance release that makes the package build and run on current Node.js. It fixes
61
-
several long-standing bugs, and those fixes change behaviour:
62
-
63
-
| Change | Before | Now |
64
-
|---|---|---|
65
-
|`SetField(index, key, value)`| Wrote the *key* into the field, ignoring the value | Writes the value, and resolves a relative `index` before pushing |
66
-
|`LoadFile` / `LoadString`| Executed the chunk, identical to `DoFile` / `DoString`| Compile and push the chunk without running it; call `Call(0, 0)` to run it |
67
-
| Lua booleans read into JS | Arrived as the numbers `1` and `0`| Arrive as `true` and `false`|
68
-
|`Push(3.5)`| Truncated to `3`| Keeps the fractional value |
69
-
|`AddPackagePath`| Appended without a separator, corrupting `package.path`, so `require` usually failed | Appends correctly, and no longer breaks on paths containing quotes |
70
-
|`ToValue` on a table | Only converted correctly when the table was at the top of the stack | Works at any stack index, including nested tables |
71
-
| Calling a method after `Close()`| Use-after-free | Throws |
72
-
|`Resume(args)`| Returned `undefined`| Returns the Lua status code |
73
-
74
-
Other things worth knowing if you are upgrading:
75
-
76
-
-**LuaJIT has been replaced by stock Lua 5.1.5.** Windows builds used to link LuaJIT 2.0.3, so
77
-
Windows users lose JIT compilation. In exchange, macOS on Apple Silicon and Linux on ARM64 work
78
-
at all, which they previously did not. The Lua C API and language are unchanged.
79
-
-**`require('lfs')` now works on every platform.** It used to be a Windows-only prebuilt DLL
80
-
loaded through an `LUA_CPATH` hack; LuaFileSystem is now compiled into the addon.
81
-
- Node.js 18 or newer is required.
58
+
## Documentation
82
59
83
-
## About
84
-
85
-
Built on the [Lua 5.1 C API](https://www.lua.org/manual/5.1/manual.html). The binding uses
86
-
[Node-API](https://nodejs.org/api/n-api.html), which is ABI-stable — a compiled build keeps
87
-
working across future Node.js releases instead of breaking on each major version.
* [Add a path to the lua package.path variable. Set a root path for lua require (see example)]
115
-
* @param{String}path
116
-
*/
117
-
lua.AddPackagePath(__dirname);
118
-
119
-
120
-
/**
121
-
* [Loads and runs the given file]
122
-
* @type{String} file
123
-
* @throws{Exception}
124
-
*/
125
-
lua.DoFile(__dirname+"/test.lua");
126
-
127
-
128
-
/**
129
-
* [Loads and runs the given string]
130
-
* @type{String} str
131
-
* @throws{Exception}
132
-
*/
133
-
lua.DoString("print('Hello world!')");
134
-
135
-
136
-
/**
137
-
* [Compiles the given file and pushes it onto the stack WITHOUT running it.
138
-
* Use Call to run it.]
139
-
* @type{String} file
140
-
* @throws{Exception}
141
-
*/
142
-
lua.LoadFile(__dirname+"/test.lua");
143
-
144
-
145
-
/**
146
-
* [Compiles the given string and pushes it onto the stack WITHOUT running it.
147
-
* Use Call to run it.]
148
-
* @type{String} str
149
-
* @throws{Exception}
150
-
*/
151
-
lua.LoadString("print('Hello world!')");
152
-
153
-
154
-
/**
155
-
* [Sets the function f as the new value of global name.
156
-
* Arguments are read off the Lua stack with ToValue; the return value is the
157
-
* number of results the function pushed.]
158
-
* @param{String}name [name of the global in lua]
159
-
* @param{Function}f [function to set]
160
-
*/
161
-
lua.RegisterFunction('add', function() {
162
-
var a =lua.ToValue(1);
163
-
var b =lua.ToValue(2);
164
-
lua.Pop(2);
165
-
lua.Push(a + b);
166
-
return1;
167
-
});
168
-
169
-
170
-
/**
171
-
* [Pops a value from the stack and sets it as the new value of global name]
172
-
* @type{String} name
173
-
*/
174
-
lua.SetGlobal("myVar");
175
-
176
-
177
-
/**
178
-
* [Pushes onto the stack the value of the global name]
179
-
* @type{String} name
180
-
*/
181
-
lua.GetGlobal('myVar');
182
-
183
-
184
-
/**
185
-
* [Does the equivalent to t[k] = v, where t is the value at the given valid index.
186
-
* Unlike the raw C API, v is passed as an argument rather than taken from the
187
-
* top of the stack.]
188
-
* @type{Number} index
189
-
* @type{String} key
190
-
* @type{*} value
191
-
* @throws{Exception} [if the value at index is not a table]
192
-
*/
193
-
lua.SetField(index, "key", value);
194
-
195
-
196
-
/**
197
-
* [Pushes onto the stack the value t[key], where t is the value at the given valid index.]
198
-
* @type{Number} index
199
-
* @type{String} key
200
-
* @throws{Exception} [if the value at index is not a table]
201
-
*/
202
-
lua.GetField(index, "key");
203
-
78
+
## How it works
204
79
205
-
/**
206
-
* [Get value at the given acceptable index]
207
-
* @type{Number} index
208
-
* @return value
209
-
*/
210
-
var value =lua.ToValue(-1);
80
+
Built on the [Lua 5.1 C API](https://www.lua.org/manual/5.1/manual.html) through
81
+
[Node-API](https://nodejs.org/api/n-api.html), which is ABI-stable — a compiled build keeps working
82
+
across future Node.js releases instead of breaking on each major version.
211
83
84
+
The API is low-level and maps closely onto the C API, and it is synchronous throughout.
212
85
213
-
/**
214
-
* [Calls a function. Gets the function and arguments from the stack. Pushes the results onto the stack. See https://www.lua.org/manual/5.1/manual.html#pdf-pcall for more information]
215
-
* @type{Number} args
216
-
* @type{Number} results
217
-
* @throws{Exception}
218
-
*/
219
-
lua.Call(args, results);
220
-
221
-
222
-
/**
223
-
* [Yields a coroutine.]
224
-
* @type{Number} args
225
-
*/
226
-
lua.Yield(args);
227
-
228
-
229
-
/**
230
-
* [Starts and resumes a coroutine in a given thread.]
231
-
* @type{Number} args
232
-
* @return{Number} [status code]
233
-
*/
234
-
lua.Resume(args);
235
-
236
-
237
-
/**
238
-
* [Pushes a value n onto the stack]
239
-
* @type n
240
-
*/
241
-
lua.Push(5);
242
-
243
-
244
-
/**
245
-
* [Pops n elements from the stack. Default value is 1]
246
-
* @type{Number} n
247
-
*/
248
-
lua.Pop();
249
-
lua.Pop(n);
250
-
251
-
252
-
/**
253
-
* [Returns the index of the top element in the stack. Because indices start at 1, this result is equal to the number of elements in the stack (and so 0 means an empty stack)]
254
-
* @return{Number}
255
-
*/
256
-
var size =lua.GetTop();
257
-
258
-
259
-
/**
260
-
* [Accepts any acceptable index, or 0, and sets the stack top to this index. If the new top is larger than the old one, then the new elements are filled with nil. If index is 0, then all stack elements are removed]
261
-
* @type{Number} index
262
-
*/
263
-
lua.SetTop(index);
264
-
265
-
266
-
/**
267
-
* [Moves the top element into the given position (and pops it), without shifting any element (therefore replacing the value at the given position)]
268
-
* @type{Number} index
269
-
*/
270
-
lua.Replace(index);
271
-
272
-
273
-
/**
274
-
* [Returns the status of the state]
275
-
* @return{Number} [compare against nodelua.STATUS.*]
276
-
*/
277
-
lua.Status();
278
-
279
-
280
-
/**
281
-
* [Controls the Lua garbage collector]
282
-
* @type{Number} what [one of nodelua.GC.*]
283
-
* @return{Number}
284
-
*/
285
-
lua.CollectGarbage(nodelua.GC.COLLECT);
286
-
287
-
288
-
/**
289
-
* [Destroys the Lua state and frees its memory. Safe to call more than once.
290
-
* Any further use of the state throws.]
291
-
*/
292
-
lua.Close();
293
-
294
-
```
295
-
296
-
### Constants
297
-
298
-
```javascript
299
-
nodelua.INFO.VERSION// "Lua 5.1"
300
-
nodelua.INFO.VERSION_NUM// 501
301
-
nodelua.INFO.COPYRIGHT
302
-
nodelua.INFO.AUTHORS
303
-
304
-
nodelua.LUA.GLOBALSINDEX// pseudo-index of the globals table
305
-
nodelua.LUA.REGISTRYINDEX// pseudo-index of the registry
306
-
307
-
nodelua.STATUS.YIELD
308
-
nodelua.STATUS.ERRRUN
309
-
nodelua.STATUS.ERRSYNTAX
310
-
nodelua.STATUS.ERRMEM
311
-
nodelua.STATUS.ERRERR
312
-
313
-
nodelua.GC.STOP
314
-
nodelua.GC.RESTART
315
-
nodelua.GC.COLLECT
316
-
nodelua.GC.COUNT
317
-
nodelua.GC.COUNTB
318
-
nodelua.GC.STEP
319
-
nodelua.GC.SETPAUSE
320
-
nodelua.GC.SETSTEPMUL
321
-
```
86
+
Descended from [NodeLua](https://github.com/brettlangdon/NodeLua) and
0 commit comments