What do the square brackets and numbers mean in Lua's documentation?

Question

What does the [x, y, z] section mean in the Lua docs? You see it on every C function.

For example, lua_gettop says:

int lua_gettop (lua_State *L);

[-0, +0, –]

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; in particular, 0 means an empty stack.

What does [-0, +0, –] mean?

Answer 1

The [-0, +0, –] section tells you how that function manipulates the Lua argument stack. There's an explanation in the Functions and Types section, but their wall of text is a bit hard to parse. I'll summarize.

Given:

[-o, +p, x]

Those elements mean:

• o: how many elements the function pops from the stack.
  • mnemonic: - because it reduces the size of the stack.
  • -0 means it pops nothing.
• p: how many elements the function pushes onto the stack.
  • mnemonic: + because it increases the size of the stack.
  • +0 means it pushes nothing.
  • Any function always pushes its results after popping its arguments.
• the form x|y means the function can push or pop x or y elements, depending on the situation;
• ? means that we cannot know how many elements the function pops/pushes by looking only at its arguments. (For instance, they may depend on what is in the stack.)
• x: whether the function may raise errors:
  • - means the function never raises any error;
  • m means the function may raise only out-of-memory errors;
  • v means the function may raise the errors explained in the text;
  • e means the function can run arbitrary Lua code, either directly or through metamethods, and therefore may raise any errors.