CODEWITHSUNDEEP
luamanual
idbrii
idbrii

Reputation: 11916

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

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?

Upvotes: 1

Views: 70

Answers (1)

idbrii
idbrii

Reputation: 11916

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.

Upvotes: 3

Related Questions