luajit

package module
v0.0.0-...-b7ab91c Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 24, 2013 License: MIT Imports: 7 Imported by: 0

README

luajit

Package luajit provides an interface to LuaJIT, a just-in-time compiler and interpreter for the Lua programming language.

Documentation

Overview

Package luajit provides an interface to LuaJIT, a just-in-time compiler and interpreter for the Lua programming language.

Index

Constants

View Source 
const (
	Version    = C.LUAJIT_VERSION
	Versionnum = C.LUAJIT_VERSION_NUM
	Copyright  = C.LUAJIT_COPYRIGHT
)
View Source 
const (
	Signature = C.LUA_SIGNATURE // mark for precompiled code (`<esc>Lua')
	Multret   = C.LUA_MULTRET   // option for multiple returns in 'call' functions
	Minstack  = C.LUA_MINSTACK  // minimum Lua stack available to a Go function
)
View Source 
const (
	Ok        = 0
	Yield     = C.LUA_YIELD
	Errrun    = C.LUA_ERRRUN
	Errsyntax = C.LUA_ERRSYNTAX
	Errmem    = C.LUA_ERRMEM
	Errerr    = C.LUA_ERRERR
)

Thread status; 0 is OK

View Source 
const (
	Registryindex = C.LUA_REGISTRYINDEX
	Environindex  = C.LUA_ENVIRONINDEX // env of running Go function
	Globalsindex  = C.LUA_GLOBALSINDEX // thread env, where globals live
)

Pseudo-indices. Unless otherwise noted, any function that accepts valid indices can also be called with these pseudo-indices, which represent some Lua values that are accessible to Go code but which are not in the stack. Pseudo-indices are used to access the thread environment, the function environment, the registry, and the upvalues of a Go function.

The thread environment (where global variables live) is always at pseudo-index Globalsindex. The environment of the running Go function is always at pseudo-index Environindex.

To access and change the value of global variables, you can use regular table operations over an environment table. For instance, to access the value of a global variable, do: 

s.Getfield(luajit.Globalsindex, varname);
View Source 
const (
	Tnone          = C.LUA_TNONE
	Tnil           = C.LUA_TNIL
	Tboolean       = C.LUA_TBOOLEAN
	Tlightuserdata = C.LUA_TLIGHTUSERDATA
	Tnumber        = C.LUA_TNUMBER
	Tstring        = C.LUA_TSTRING
	Ttable         = C.LUA_TTABLE
	Tfunction      = C.LUA_TFUNCTION
	Tuserdata      = C.LUA_TUSERDATA
	Tthread        = C.LUA_TTHREAD
)

Basic types

View Source 
const (
	// Stops the garbage collector.
	GCstop = C.LUA_GCSTOP
	// Restarts the garbage collector.
	GCrestart = C.LUA_GCRESTART
	// Performs a full garbage-collection cycle.
	GCcollect = C.LUA_GCCOLLECT
	// Returns the current amount of memory (in Kbytes) in use by Lua.
	GCcount = C.LUA_GCCOUNT
	// Returns the remainder of dividing the current amount of bytes of memory
	// in use by Lua by 1024.
	GCcountb = C.LUA_GCCOUNTB
	// Performs an incremental step of garbage collection. The step "size" is
	// controlled by data (larger values mean more steps) in a non-specified
	// way. If you want to control the step size you must experimentally
	// tune the value of data. The function returns 1 if the step finished a
	// garbage-collection cycle.
	GCstep = C.LUA_GCSTEP
	// Sets data as the new value for the pause of the collector. The function
	// returns the previous value of the pause.
	GCsetpause = C.LUA_GCSETPAUSE
	// Sets data as the new value for the step multiplier of the collector. The
	// function returns the previous value of the step multiplier.
	GCsetstepmul = C.LUA_GCSETSTEPMUL
)

Garbage-collection function and options

View Source 
const (
	// The call hook is called when the interpreter calls a function. The
	// hook is called just after LuaJIT enters the new function, before
	// the function gets its arguments.
	Hookcall = C.LUA_HOOKCALL
	// The return hook is called when the interpreter returns from
	// a function. The hook is called just before LuaJIT leaves the
	// function. You have no access to the values to be returned by
	// the function.
	Hookret = C.LUA_HOOKRET
	// The line hook is called when the interpreter is about to start
	// the execution of a new line of code, or when it jumps back in
	// the code (even to the same line). (This event only happens while
	// LuaJIT is executing a Lua function.)
	Hookline = C.LUA_HOOKLINE
	// The count hook is called after the interpreter executes every
	// count instructions. (This event only happens while LuaJIT is
	// executing a Lua function.)
	Hookcount   = C.LUA_HOOKCOUNT
	Hooktailret = C.LUA_HOOKTAILRET
)

Debug event codes

View Source 
const (
	Maskcall  = 1 << Hookcall
	Maskret   = 1 << Hookret
	Maskline  = 1 << Hookline
	Maskcount = 1 << Hookcount
)

Debug event masks

View Source 
const (
	Filehandle  = C.LUA_FILEHANDLE
	Colibname   = C.LUA_COLIBNAME   // coroutine
	Tablibname  = C.LUA_TABLIBNAME  // table
	IOlibname   = C.LUA_IOLIBNAME   // io
	OSlibname   = C.LUA_OSLIBNAME   // os
	Strlibname  = C.LUA_STRLIBNAME  // string
	Mathlibname = C.LUA_MATHLIBNAME // math
	Dblibname   = C.LUA_DBLIBNAME   // debug
	Loadlibname = C.LUA_LOADLIBNAME // package
)

lualib constants

View Source 
const (
	// Turn the whole JIT compiler on or off or flush the whole
	// cache of compiled code.
	Modeengine = C.LUAJIT_MODE_ENGINE
	// Set debug mode (idx = level).
	Modedebug = C.LUAJIT_MODE_DEBUG
	// This sets the mode for the function at the stack index idx or the
	// parent of the calling function (idx = 0). It either enables JIT
	// compilation for a function, disables it and flushes any already
	// compiled code or only flushes already compiled code. This applies
	// recursively to all sub-functions of the function with Modeallfunc
	// or only to the sub-functions with Modeallsubfunc.
	Modefunc       = C.LUAJIT_MODE_FUNC
	Modeallfunc    = C.LUAJIT_MODE_ALLFUNC
	Modeallsubfunc = C.LUAJIT_MODE_ALLSUBFUNC
	// Flushes the specified root trace and all of its side traces from
	// the cache. The code for the trace will be retained as long as
	// there are any other traces which link to it.
	Modetrace = C.LUAJIT_MODE_TRACE
	// This mode defines a wrapper function for calls to Go functions. If
	// called with Modeon, the stack index at idx must be a lightuserdata
	// object holding a pointer to the wrapper function. From now on all
	// Go functions are called through the wrapper function. If called
	// with Modeoff this mode is turned off and all Go functions are
	// directly called.
	Modewrapfunc = C.LUAJIT_MODE_WRAPCFUNC

	Modemax = C.LUAJIT_MODE_MAX
)

VM modes

View Source 
const (
	Modeoff   = C.LUAJIT_MODE_OFF   // turn feature off
	Modeon    = C.LUAJIT_MODE_ON    // turn feature on
	Modeflush = C.LUAJIT_MODE_FLUSH // flush JIT-compiled code
)

VM mode flags

These should be ORed with the VM mode given to (*State).Setmode, for example: 

s.Setmode(0, luajit.Modeengine|luajit.Modeon)

Variables

This section is empty.

Functions

func Upvalueindex 

func Upvalueindex(n int) int

Returns the pseudo-index for the nth upvalue of a Go closure.

Whenever a Go closure is called from Lua, its upvalues are located at specific pseudo-indices. These pseudo-indices are located using Upvalueindex. The first value associated with a function is at position Upvalueindex(1), and so on.

Types

type Debug 

type Debug struct {
	// The event that triggered the current hook function.
	Event int
	// A reasonable name for the given function. Because functions in
	// Lua are first-class values, they do not have a fixed name: some
	// functions can be the value of multiple global variables, while
	// others can be stored only in a table field. The State.Getinfo
	// function checks how the function was called to find a suitable
	// name. If it cannot find a name, then name is an empty string.
	Name string
	// Explains the name field. The value of namewhat can be "global",
	// "local", "method", "field", "upvalue", or "" (the empty string),
	// according to how the function was called. (Lua uses the empty
	// string when no other option seems to apply.)
	Namewhat string
	// The string "Lua" if the function is a Lua function, "Go" if it
	// is a Go function, "main" if it is the main part of a chunk, and
	// "tail" if it was a function that did a tail call. In the latter
	// case, Lua has no other information about the function.
	What string
	// If the function was defined in a string, then Source is that
	// string. If the function was defined in a file, then source starts
	// with a '@' followed by the file name.
	Source string
	// "Printable" version of Source, for use in error messages.
	Shortsrc string
	// The current line where the given function is executing. When no
	// line information is available, currentline is set to -1.
	Currentline int
	// The number of upvalues of the function.
	Nups int
	// The line number where the definition of the function starts.
	Linedefined int
	// The line number where the definition of the function ends.
	Lastlinedefined int
	// contains filtered or unexported fields
}

A Debug is used to carry different pieces of information about an active function. Getstack fills only the private part of this structure, for later use. To fill the other fields of Debug with useful information, call Getinfo.

func Newdebug 

func Newdebug(s *State) *Debug

func (*Debug) Getinfo 

func (d *Debug) Getinfo(what string) error

Returns information about a specific function or function invocation.

To get information about a function invocation, the parameter ar must be a valid activation record that was filled by a previous call to Getstack or given as argument to a hook.

To get information about a function you push it onto the stack and start the what string with the character '>'. (In that case, Getinfo pops the function in the top of the stack.) For instance, to know in which line a function f was defined, you can write the following code: 

d := luajit.Newdebug(s)
s.Getfield(luajit.Globalsindex, "f")  // get global 'f'
d.Getinfo(">S")
fmt.Printf("%d\n", d.Linedefined);

Each character in the string what selects some fields of the structure ar to be filled or a value to be pushed on the stack: 

'n'	fills in the field Name and Namewhat
'S'	fills in the fields Source, Shortsrc, Linedefined,
	Lastlinedefined, and What
'l'	fills in the field Currentline
'u'	fills in the field Nups
'f'	pushes onto the stack the function that is running at the
	given level
'L'	pushes onto the stack a table whose indices are the numbers of
	the lines that are valid on the function. (A valid line is a line
	with some associated code, that is, a line where you can put a break
	point. Invalid lines include empty lines and comments.)

func (*Debug) Getlocal 

func (d *Debug) Getlocal(n int) string

Gets information about a local variable of a given activation record. The parameter ar must be a valid activation record that was filled by a previous call to Getstack or given as argument to a hook. The index n selects which local variable to inspect (1 is the first parameter or active local variable, and so on, until the last active local variable). Getlocal pushes the variable's value onto the stack and returns its name.

Variable names starting with '(' (open parentheses) represent internal variables (loop control variables, temporaries, and Go function locals).

Returns an empty string (and pushes nothing) when the index is greater than the number of active local variables.

func (*Debug) Getstack 

func (d *Debug) Getstack(level int) error

Gets information about the interpreter runtime stack.

This function fills parts of a Debug structure with an identification of the activation record of the function executing at a given level. Level 0 is the current running function, whereas level n+1 is the function that has called level n. When there are no errors, Getstack returns nil; when called with a level greater than the stack depth, it returns the error.

func (*Debug) Setlocal 

func (d *Debug) Setlocal(n int) (string, error)

Sets the value of a local variable of a given activation record. Parameters d and n are as in Getlocal. Setlocal assigns the value at the top of the stack to the variable and returns its name. It also pops the value from the stack.

Returns an error (and pops nothing) when the index is greater than the number of active local variables.

type Gofunction 

type Gofunction func(*State) int

A Gofunction is a Go function that may be registered with the Lua interpreter and called by Lua programs.

In order to communicate properly with Lua, a Go function must use the following protocol, which defines the way parameters and results are passed: a Go function receives its arguments from Lua in its stack in direct order (the first argument is pushed first). So, when the function starts, s.Gettop returns the number of arguments received by the function. The first argument (if any) is at index 1 and its last argument is at index s.Gettop. To return values to Lua, a Go function just pushes them onto the stack, in direct order (the first result is pushed first), and returns the number of results. Any other value in the stack below the results will be properly discarded by Lua. Like a Lua function, a Go function called by Lua can also return many results.

As an example, the following function receives a variable number of numerical arguments and returns their average and sum: 

func foo(s *luajit.State) int {
	n := s.Gettop()		// number of arguments
	sum := 0.0
	for i := 1; i <= n; i++ {
		if !s.Isnumber(i) {
			s.Pushstring("incorrect argument")
			s.Error()
		}
		sum += s.Tonumber(i)
	}
	s.Pushnumber(sum/n)	// first result
	s.Pushnumber(sum)	// second result
	return 2		// number of results
}

type Hook 

type Hook func(s *State, ar *Debug)

Type for debug hook functions.

Whenever a hook is called, its ar argument has its Event field set to the specific event that triggered the hook. LuaJIT identifies these events with the following constants: Hookcall, Hookret, Hooktailret, Hookline, and Hookcount. Moreover, for line events, the Currentline field is also set. To get the value of any other field in ar, the hook must call Getinfo. For return events, event can be Hookret, the normal value, or Hooktailret. In the latter case, LuaJIT is simulating a return from a function that did a tail call; in this case, it is useless to call Getinfo.

While LuaJIT is running a hook, it disables other calls to hooks. Therefore, if a hook calls back LuaJIT to execute a function or a chunk, this execution occurs without any calls to hooks.

type State 

type State struct {
	// contains filtered or unexported fields
}

A State keeps all state of a LuaJIT interpreter.

func Newstate 

func Newstate() *State

Creates & initializes a new State and returns a pointer to it. Returns nil on error.

func (*State) Call 

func (s *State) Call(nargs, nresults int)

Calls a function.

To call a function you must use the following protocol: first, the function to be called is pushed onto the stack; then, the arguments to the function are pushed in direct order; that is, the first argument is pushed first. Finally you call Call; nargs 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 nresults, unless nresults is luajit.Multret. In this case, all results from the function are pushed. Lua takes care that the returned values fit into the stack space. 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.

Any error inside the called function is propagated upwards (with a longjmp).

func (*State) Checkstack 

func (s *State) Checkstack(extra int) bool

Ensures that there are at least extra free stack slots in the stack. It returns false if it cannot grow the stack to that size. This function never shrinks the stack; if the stack is already larger than the new size, it is left unchanged.

func (*State) Close 

func (s *State) Close()

Destroys all objects in the given Lua state (calling the corresponding garbage-collection metamethods, if any) and frees all dynamic memory used by this state. On several platforms, you may not need to call this function, because all resources are naturally released when the host program ends. On the other hand, long-running programs, such as a daemon or a web server, might need to release states as soon as they are not needed, to avoid growing too large.

func (*State) Concat 

func (s *State) Concat(n int)

Concatenates the n values at the top of the stack, pops them, and leaves the result at the top. If n is 1, the result is the single value on the stack (that is, the function does nothing); if n is 0, the result is the empty string. Concatenation is performed following the usual semantics of Lua.

func (*State) Createtable 

func (s *State) Createtable(narr, nrec int)

Creates a new empty table and pushes it onto the stack. The new table has space pre-allocated for narr array elements and nrec non-array elements. This pre-allocation is useful when you know exactly how many elements the table will have. Otherwise you can use the function Newtable.

func (*State) Dump 

func (s *State) Dump(w *io.Writer) error

Dumps a function as a binary chunk. Receives a Lua function on the top of the stack and produces a binary chunk that, if loaded again, results in a function equivalent to the one dumped. As it produces parts of the chunk, Dump writes to w.

This function does not pop the Lua function from the stack.

func (*State) Equal 

func (s *State) Equal(i1, i2 int) bool

Returns true if the two values in valid indices i1 and i2 are equal, following the semantics of the Lua == operator (that is, may call metamethods). Otherwise returns false. Also returns false if any of the indices is invalid.

func (*State) Error 

func (s *State) Error()

Generates a Lua error. The error message (which can actually be a Lua value of any type) must be on the stack top. This function does a long jump, and therefore never returns.

func (*State) Gc 

func (s *State) Gc(what, data int) int

Controls the garbage collector.

This function performs several tasks, according to the value of the parameter what, which must be one of the luajit.GC* constants.

func (*State) Getfenv 

func (s *State) Getfenv(index int)

Pushes onto the stack the environment table of the value at the given index.

func (*State) Getfield 

func (s *State) Getfield(index int, k string)

Pushes onto the stack the value t[k], where t is the value at the given valid index.

func (*State) Getglobal 

func (s *State) Getglobal(name string)

Pushes onto the stack the value of the global name.

func (*State) Getmetatable 

func (s *State) Getmetatable(index int)

Pushes onto the stack the metatable associated with name tname in the registry.

func (*State) Gettable 

func (s *State) Gettable(index int)

Pushes onto the stack the value t[k], where t is the value at the given valid index and k is the value at the top of the stack.

This function pops the key from the stack (putting the resulting value in its place). As in Lua, this function may trigger a metamethod for the "index" event

func (*State) Gettop 

func (s *State) Gettop() int

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).

func (*State) Getupvalue 

func (s *State) Getupvalue(funcindex, n int) (string, error)

Gets information about a closure's upvalue. (For Lua functions, upvalues are the external local variables that the function uses, and that are consequently included in its closure.) Getupvalue gets the index n of an upvalue, pushes the upvalue's value onto the stack, and returns its name. funcindex points to the closure in the stack. (Upvalues have no particular order, as they are active through the whole function. So, they are numbered in an arbitrary order.)

Returns an error (and pushes nothing) when the index is greater than the number of upvalues. For Go functions, this function uses the empty string "" as a name for all upvalues.

func (*State) Insert 

func (s *State) Insert(index int)

Moves the top element into the given valid index, shifting up the elements above this index to open space. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.

func (*State) Isboolean 

func (s *State) Isboolean(index int) bool

Returns true if the value at the given valid index has type boolean, and false otherwise.

func (*State) Isfunction 

func (s *State) Isfunction(index int) bool

Returns true if the value at the given valid index is a function (either Go or Lua), and false otherwise.

func (*State) Isgofunction 

func (s *State) Isgofunction(index int) bool

Returns true if the value at the given valid index is a Go function, and false otherwise.

func (*State) Islightuserdata 

func (s *State) Islightuserdata(index int) bool

Returns true if the value at the given valid index is light userdata, and false otherwise.

func (*State) Isnil 

func (s *State) Isnil(index int) bool

Returns true if the value at the given valid index is nil, and false otherwise.

func (*State) Isnone 

func (s *State) Isnone(index int) bool

Returns true if the given valid index is not valid (that is, it refers to an element outside the current stack), and false otherwise.

func (*State) Isnoneornil 

func (s *State) Isnoneornil(index int) bool

Returns true if the given valid index is not valid (that is, it refers to an element outside the current stack) or if the value at this index is nil, and false otherwise.

func (*State) Isnumber 

func (s *State) Isnumber(index int) bool

Returns true if the value at the given valid index is a number, and false otherwise.

func (*State) Isstring 

func (s *State) Isstring(index int) bool

Returns true if the value at the given valid index is a string, and false otherwise.

func (*State) Istable 

func (s *State) Istable(index int) bool

Returns true if the value at the given valid index is a table, and false otherwise.

func (*State) Isthread 

func (s *State) Isthread(index int) bool

Returns true if the value at the given valid index is a thread, and false otherwise.

func (*State) Isuserdata 

func (s *State) Isuserdata(index int) bool

Returns true if the value at the given acceptable index is a userdata (either full or light), and false otherwise.

func (*State) Lessthan 

func (s *State) Lessthan(i1, i2 int) bool

Returns true if the value at valid index i1 is smaller than the value at index i2, following the semantics of the Lua < operator (that is, may call metamethods). Otherwise returns false. Also returns false if any of the indices is invalid.

func (*State) Load 

func (s *State) Load(chunk *bufio.Reader, chunkname string) error

Reads a Lua chunk from a *bufio.Reader. If there are no errors, Load pushes the compiled chunk as a Lua function on top of the stack, and returns nil.

The chunkname argument gives a name to the chunk, which is used for error messages and in debug information

Load only loads a chunk; it does not run it.

Load automatically detects whether the chunk is text or binary, and loads it accordingly (see program luac).

func (*State) Loadfile 

func (s *State) Loadfile(filename string) error

Loads the specified file as a Lua chunk. The first line in the file is ignored if it starts with '#'.

This function only loads the chunk; it does not run it.

func (*State) Loadstring 

func (s *State) Loadstring(str string) error

Loads a string as a Lua chunk.

This function only loads the chunk; it does not run it.

func (*State) Newtable 

func (s *State) Newtable()

Creates a new empty table and pushes it onto the stack. It is equivalent to Createtable(0, 0).

func (*State) Newthread 

func (s *State) Newthread() *State

Creates a new thread, pushes it on the stack, and returns a pointer to a State that represents this new thread. The new state returned by this function shares with the original state all global objects (such as tables), but has an independent execution stack.

There is no explicit function to close or to destroy a thread. Threads are subject to garbage collection, like any Lua object.

func (*State) Next 

func (s *State) Next(index int) int

Pops a key from the stack, and pushes a key-value pair from the table at the given index (the "next" pair after the given key). If there are no more elements in the table, then Next returns 0 (and pushes nothing).

A typical traversal looks like this: 

// table is in the stack at index 't'
s.Pushnil()	// first key
for s.Next(t) != 0 {
	// use key (at index -2) and value (index -1)
	fmt.Printf("%s - %s\n",
		s.Typename(s.Type(-2)),
		s.Typename(s.Type(-1)))
	// remove value, keep key for next iteration
	s.Pop(1)
}

func (*State) Objlen 

func (s *State) Objlen(index int) int

Returns the "length" of the value at the given valid index: for strings, this is the string length; for tables, this is the result of the length operator ('#'); for userdata, this is the size of the block of memory allocated for the userdata; for other values, it is 0.

func (*State) Openlibs 

func (s *State) Openlibs()

Opens all standard Lua libraries into the given state.

func (*State) Pcall 

func (s *State) Pcall(nargs, nresults, errfunc int) error

Calls a function in protected mode.

Both nargs and nresults have the same meaning as in Call. If there are no errors during the call, Pcall behaves exactly like Call. However, if there is any error, Pcall catches it, pushes a single value on the stack (the error message), and returns an error code. Like Call, Pcall always removes the function and its arguments from the stack.

If errfunc is 0, then the error message returned on the stack is exactly the original error message. Otherwise, errfunc is the stack index of an error handler function. (In the current implementation, this index cannot be a pseudo-index.) In case of runtime errors, this function will be called with the error message and its return value will be the message returned on the stack by Pcall.

Typically, the error handler function is used to add more debug information to the error message, such as a stack traceback. Such information cannot be gathered after the return of Pcall, since by then the stack has unwound.

func (*State) Pop 

func (s *State) Pop(index int)

Pops n elements from the stack.

func (*State) Pushboolean 

func (s *State) Pushboolean(b bool)

Pushes a boolean value with value b onto the stack.

func (*State) Pushclosure 

func (s *State) Pushclosure(fn Gofunction, n int)

Pushes a new Go closure onto the stack.

When a Go function is created, it is possible to associate some values with it, thus creating a Go closure; these values are then accessible to the function whenever it is called. To associate values with a Go function, first these values should be pushed onto the stack (when there are multiple values, the first value is pushed first). Then Pushclosure is called to create and push the Go function onto the stack, with the argument n telling how many values should be associated with the function. Pushclosure also pops these values from the stack.

The maximum value for n is 254.

func (*State) Pushfstring 

func (s *State) Pushfstring(format string, v ...interface{}) *string

Formats a string and pushes it into the stack. Provides all formatting verbs found in package fmt. Returns a pointer to the resultant formatted string.

func (*State) Pushfunction 

func (s *State) Pushfunction(fn Gofunction)

Pushes a Go function onto the stack. This function receives a pointer to a Go function and pushes onto the stack a Lua value of type function that, when called, invokes the corresponding Go function.

Any function to be registered in Lua must follow the correct protocol to receive its parameters and return its results (see Gofunction).

func (*State) Pushinteger 

func (s *State) Pushinteger(n int)

Pushes a number with value n onto the stack.

func (*State) Pushlightuserdata 

func (s *State) Pushlightuserdata(p unsafe.Pointer)

Pushes a light userdata onto the stack.

Userdata represent Go values in Lua. A light userdata represents a pointer. It is a value (like a number): you do not create it, it has no individual metatable, and it is not collected (as it was never created). A light userdata is equal to "any" light userdata with the same address.

func (*State) Pushnil 

func (s *State) Pushnil()

Pushes a nil value onto the stack.

func (*State) Pushnumber 

func (s *State) Pushnumber(n float64)

Pushes a number with value n onto the stack.

func (*State) Pushstring 

func (s *State) Pushstring(str string)

Pushes the string str onto the stack.

func (*State) Pushthread 

func (s *State) Pushthread() int

Pushes the thread represented by s onto the stack. Returns 1 if this thread is the main thread of its state.

func (*State) Pushvalue 

func (s *State) Pushvalue(index int)

Pushes a copy of the element at the given valid index onto the stack.

func (*State) Rawequal 

func (s *State) Rawequal(i1, i2 int) bool

Returns true if the two values at valid indices i1 and i2 are primitively equal (that is, without calling metamethods). Otherwise returns false. Also returns false if any of the indices are invalid.

func (*State) Rawget 

func (s *State) Rawget(index int)

Similar to Gettable, but does a raw access (i.e., without metamethods).

func (*State) Rawgeti 

func (s *State) Rawgeti(index, n int)

Pushes onto the stack the value t[n], where t is the value at the given valid index. The access is raw; that is, it does not invoke metamethods.

func (*State) Rawset 

func (s *State) Rawset(index int)

Similar to Settable, but does a raw assignment (i.e., without metamethods).

func (*State) Rawseti 

func (s *State) Rawseti(index, n int)

Does the equivalent of t[n] = v, where t is the value at the given valid index and v is the value at the top of the stack.

This function pops the value from the stack. The assignment is raw; that is, it does not invoke metamethods.

func (*State) Register 

func (s *State) Register(fn Gofunction, name string)

Sets the Go function fn as the new value of global name.

func (*State) Remove 

func (s *State) Remove(index int)

Removes the element at the given valid index, shifting down the elements above this index to fill the gap. Cannot be called with a pseudo-index, because a pseudo-index is not an actual stack position.

func (*State) Replace 

func (s *State) Replace(index int)

Moves the top element into the given position (and pops it), without shifting any element (therefore replacing the value at the given position).

func (*State) Resume 

func (s *State) Resume(narg int) (yield bool, e error)

Starts and resumes a coroutine in a given thread.

To start a coroutine, you first create a new thread (see Newthread); then you push onto its stack the main function plus any arguments; then you call Resume, with narg being the number of arguments. This call returns when the coroutine suspends or finishes its execution. When it returns, the stack contains all values passed to Yield, or all values returned by the body function. Resume returns (true, nil) if the coroutine yields, (false, nil) if the coroutine finishes its execution without errors, or (false, error) in case of errors (see Pcall).

In case of errors, the stack is not unwound, so you can use the debug API over it. The error message is on the top of the stack.

To resume a coroutine, you remove any results from the last Yield, put on its stack only the values to be passed as results from the yield, and then call Resume.

func (*State) Setfield 

func (s *State) Setfield(index int, k string)

Does the equivalent to t[k] = v, where t is the value at the given valid index and v is the value at the top of the stack.

This function pops the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event

func (*State) Setglobal 

func (s *State) Setglobal(name string)

Pops a value from the stack and sets it as the new value of global name.

func (*State) Sethook 

func (s *State) Sethook(fn Hook, mask, count int) error

Sets the debugging hook function.

Argument fn is the hook function. mask specifies on which events the hook will be called: it is formed by a bitwise OR of the constants Maskcall, Maskret, Maskline, and Maskcount. The count argument is only meaningful when the mask includes Maskcount. The hook is called for each event type present in mask.

A hook is disabled by setting mask to 0.

func (*State) Setmetatable 

func (s *State) Setmetatable(index int) int

Pops a table from the stack and sets it as the new metatable for the value at the given valid index.

func (*State) Setmode 

func (s *State) Setmode(idx, mode int) error

Controls VM

The idx argument is either 0 or a stack index (similar to the other Lua/Go API functions).

The mode argument specifies the VM mode, which is ORed with a flag. The flag can be Modeon to turn a feature on, Modeoff to turn a feature off, or Modeflush to flush cached code.

func (*State) Settable 

func (s *State) Settable(index int)

Does the equivalent to t[k] = v, where t is the value at the given valid index, v is the value at the top of the stack, and k is the value just below the top.

This function pops both the key and the value from the stack. As in Lua, this function may trigger a metamethod for the "newindex" event.

func (*State) Settop 

func (s *State) Settop(index int)

Accepts any valid 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.

func (*State) Setupvalue 

func (s *State) Setupvalue(funcindex, n int) (string, error)

Sets the value of a closure's upvalue. It assigns the value at the top of the stack to the upvalue and returns its name. It also pops the value from the stack. Parameters funcindex and n are as in the Getupvalue.

Returns an error (and pops nothing) when the index is greater than the number of upvalues.

func (*State) Status 

func (s *State) Status() int

Returns the status of the thread s.

The status can be 0 for a normal thread, an error code if the thread finished its execution with an error, or luajit.Yield if the thread is suspended.

func (*State) Strlen 

func (s *State) Strlen(index int) int

func (*State) Toboolean 

func (s *State) Toboolean(index int) bool

Converts the Lua value at the given valid index to a Go boolean value. Like all tests in Lua, Toboolean returns true for any Lua value different from false and nil; otherwise it returns false. It also returns false when called with a non-valid index. (If you want to accept only actual boolean values, use Isboolean to test the value's type.)

func (*State) Togofunction 

func (s *State) Togofunction(index int) (Gofunction, error)

Converts a value at the given valid index to a Go function. That value must be a Go function; otherwise, returns an error.

func (*State) Tointeger 

func (s *State) Tointeger(index int) int

Converts the Lua value at the given valid index to a Go int. The Lua value must be a number or a string convertible to a number; otherwise, Tointeger returns 0.

If the number is not an integer, it is truncated in some non-specified way.

func (*State) Tonumber 

func (s *State) Tonumber(index int) float64

Converts the Lua value at the given valid index to a float64. The Lua value must be a number or a string convertible to a number; otherwise, Tonumber returns 0.

func (*State) Topointer 

func (s *State) Topointer(index int) unsafe.Pointer

Converts the value at the given acceptable index to a uintptr. The value can be a userdata, a table, a thread, or a function; otherwise, Topointer returns nil. Different objects will give different pointers. There is no way to convert the pointer back to its original value.

Typically this function is used only for debug information.

func (*State) Tostring 

func (s *State) Tostring(index int) string

Converts the Lua value at the given valid index to a Go string. The Lua value must be a string or a number; otherwise, the function returns an empty string. If the value is a number, then Tostring also changes the actual value in the stack to a string. (This change confuses Next when Tostring is applied to keys during a table traversal). The string always has a zero ('\0') after its last character (as in C), but can contain other zeros in its body.

func (*State) Tothread 

func (s *State) Tothread(index int) *State

Converts the value at the given valid index to a Lua thread (represented as a *State). This value must be a thread; otherwise, the function returns nil.

func (*State) Touserdata 

func (s *State) Touserdata(index int) unsafe.Pointer

If the value at the given valid index is a full userdata, returns its block address. If the value is a light userdata, returns its pointer. Otherwise, returns unsafe.Pointer(nil).

func (*State) Type 

func (s *State) Type(index int) int

Returns the type of the value in the given valid index, or Tnone for a non-valid index (that is, an index to an "empty" stack position). The types returned by lua_type are coded by the following constants defined in const.go: Tnil, Tnumber, Tboolean, Tstring, Ttable, Tfunction, Tuserdata, Tthread, and Tlightuserdata.

func (*State) Typename 

func (s *State) Typename(tp int) string

Returns the name of the type encoded by the value tp, which must be one the values returned by Type.

func (*State) Xmove 

func (to *State) Xmove(from *State, n int)

Exchange values between different threads of the /same/ global state.

This function pops n values from the stack from, and pushes them onto the stack to.

func (*State) Yield 

func (s *State) Yield(nresults int) int

Yields a coroutine.

This function should only be called as the return expression of a Go function, as follows: 

return s.Yield(nresults)

When a Go function calls Yield in that way, the running coroutine suspends its execution, and the call to Resume that started this coroutine returns. The parameter nresults is the number of values from the stack that are passed as results to Resume.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.