luastack
: Lua Stack manipulation¶
Note
luastack
is not a part of thegmod
package. So, instead of:
from gmod.luastack import *
or:
from gmod import *
# Trying to use luastack
you should use:
from luastack import *
# Using luastack
This module contains functions for manipulating the Lua stack. The lowest level of Garry’s Mod Lua interoperability.
Lua Stack description¶
Lua uses a virtual stack to pass values to and from C.
Each element in this stack represents a Lua value (nil
, number, string, etc.).
For convenience, most query operations in the API do not follow a strict stack discipline. Instead, they can refer to any element in the stack by using an index:
- A positive index represents an absolute stack position (starting at 1)
- A negative index represents an offset relative to the top of the stack.
More specifically, if the stack has n elements, then index 1 represents the first element (that is, the element that was pushed onto the stack first) and index n represents the last element; index -1 also represents the last element (that is, the element at the top) and index -n represents the first element. We say that an index is valid if it lies between 1 and the stack top (that is, if 1 ≤ abs(index) ≤ top).
-
IN_GMOD
¶ Boolean constant which is
True
if GPython system is running during a Garry’s Mod session. This constant is used in GPython libraries for preventing some code from executing when generating documentation.
Stack manipulation¶
-
top
()¶ 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).
-
equal
(a: int, b: int) → bool¶ Returns
True
if the two values in acceptable indicesa
andb
are equal, following the semantics of the Lua==
operator (that is, may call metamethods). Otherwise returnsFalse
. Also returnsFalse
if any of the indices is non valid.
-
raw_equal
(a: int, b: int) → bool¶ Returns
True
if the two values in acceptable indicesa
andb
are primitively equal (that is, without calling metamethods). Otherwise returnsFalse
. Also returnsFalse
if any of the indices are non valid.
-
insert
(destination_index: int)¶ Moves the top element into the given valid index, shifting up the elements above this index to open space.
-
throw_error
(message: bytes)¶ Raises a Lua error with the given
bytes
message.It also adds at the beginning of the message the file name and the line number where the error occurred, if this information is available.
-
create_table
() → None¶ Creates a new empty table and pushes it onto the stack.
-
push
(stack_pos: int)¶
-
push_nil
()¶ Pushes a
nil
value onto the stack.
-
push_number
(num)¶ Pushes a number
num
onto the stack.
-
push_string
(val: bytes)¶ Pushes a
bytes
object onto the stack.You can push
str
like this:s = '...' push_string(s.encode())
-
push_bool
(val: bool)¶ Pushes a boolean value
val
onto the stack.
-
pop
(amt: int = 1) → None¶ Pops
amt
elements from the stack.
-
clear
()¶ Clears the stack (pops all values).
-
get_table
(stack_pos: int) → None¶ Pushes onto the stack the value
t[k]
, wheret
is the value at the given valid indexstack_pos
andk
is the value at the top of the stack.This function pops the key from the stack (putting the resulting value in its place).
-
get_field
(stack_pos: int, name: bytes) → None¶ Pushes onto the stack the value
t[name]
, wheret
is the value at the given valid indexstack_pos
.
-
set_table
(stack_pos: int)¶ Does the equivalent to
t[k] = v
, wheret
is the value at the given valid indexstack_pos
,v
is the value at the top of the stack, andk
is the value just below the top.This function pops both the key and the value from the stack.
-
set_field
(stack_pos: int, name: bytes)¶ Does the equivalent to
t[k] = v
, wheret
is the value at the given valid indexstack_pos
andv
is the value at the top of the stack.This function pops the value from the stack.
-
call
(args: int, results: int)¶ Calls a function.
To call a function you must use the following protocol:
- The function to be called is pushed onto the stack
- The arguments to the function are pushed in direct order; that is, the first argument is pushed first.
- You call this function;
args
is the number of arguments that you pushed onto the stack.
All arguments and the function value are popped from the stack when the function is called. The function results are pushed onto the stack when the function returns. The number of results is adjusted to
results
. The function results are pushed onto the stack in direct order (the first result is pushed first), so that after the call the last result is on the top of the stack.The following example shows how the host program can do the equivalent to this Lua code:
a = f("how", t.x, 14)
Here it is with GPython’s luastack:
push_special(Special.GLOBAL) get_field(1, "f") # function to be called push_string("how") # 1st argument get_field(1, "t") # table to be indexed get_field(-1, "x") # push result of t.x (2nd arg) remove(-2) # remove 't' from the stack push_number(14) # 3rd argument call(3, 1) # call 'f' with 3 arguments and 1 result set_field(1, "a") # set global 'a'
Note that the code above is “balanced”: at its end, the stack is back to its original configuration. This is considered good programming practice.
-
get_string
(stack_pos: int = -1) → bytes¶ Returns the
bytes
value of a string item atstack_pos
index of the stack.Negative values can be used for indexing the stack from top.
-
get_number
(stack_pos: int = -1) → float¶ Returns the
float
value of a number item atstack_pos
index of the stack.Negative values can be used for indexing the stack from top.
-
get_bool
(stack_pos: int = -1) → bool¶ Returns the boolean value of a boolean item at
stack_pos
index of the stack.Negative values can be used for indexing the stack from top.
-
create_ref
() → int¶ Saves the value at the top of the stack to a reference, pops it and returns the reference ID.
-
free_ref
(ref: int)¶ Frees the reference with ID
ref
.
-
push_ref
(ref: int)¶ Pushes the value saved in the reference with ID
ref
onto the stack.
-
get_type
(stack_pos: int) → ValueType¶ Returns
ValueType
enum member which corresponds to the type of the value at indexstack_pos
of the stack.
-
get_type_name
(type: ValueType) → str¶ Returns a lowercase string representation of
type
type.
-
is_type
(stack_pos: int, type: ValueType) → bool¶ Returns
True
if the value’s type at indexstack_pos
is the same astype
argument.
Special values¶
-
class
Special
(enum.enum)¶ Enum of special values. The only practically usable value is
Special.GLOBAL
.Special values can be pushed with
push_special()
.-
GLOBAL
¶ Represents the global Lua namespace (
_G
).
-
ENVIRONMENT
¶ Represents the environment table.
-
REGISTRY
¶ Represents the registry table. More data can be found in Official Lua documentation.
-
Value types¶
-
class
ValueType
(enum.enum)¶ Enum of Lua value types.
NIL, BOOL, LIGHTUSERDATA, NUMBER, STRING, TABLE, FUNCTION, USERDATA, THREAD, # UserData ENTITY, VECTOR, ANGLE, PHYSOBJ, SAVE, RESTORE, DAMAGEINFO, EFFECTDATA, MOVEDATA, RECIPIENTFILTER, USERCMD, SCRIPTEDVEHICLE, # Client Only MATERIAL, PANEL, PARTICLE, PARTICLEEMITTER, TEXTURE, USERMSG, CONVAR, IMESH, MATRIX, SOUND, PIXELVISHANDLE, DLIGHT, VIDEO, FILE