org.luaj.vm2
Class Globals

java.lang.Object
  org.luaj.vm2.Varargs
      org.luaj.vm2.LuaValue
          org.luaj.vm2.LuaTable
              org.luaj.vm2.Globals

public class Globals
extends LuaTable

Global environment used by luaj. Contains global variables referenced by executing lua.

Constructing and Initializing Instances

Typically, this is constructed indirectly by a call to JsePlatform.standardGlobals() or JmePlatform.standardGlobals(), and then used to load lua scripts for execution as in the following example.

 Globals globals = JsePlatform.standardGlobals();
 globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
  

The creates a complete global environment with the standard libraries loaded.

For specialized circumstances, the Globals may be constructed directly and loaded with only those libraries that are needed, for example.

 Globals globals = new Globals();
 globals.load( new BaseLib() ); 
  

Loading and Executing Lua Code

Globals contains convenience functions to load and execute lua source code given a Reader. A simple example is:

 globals.load( new StringReader("print 'hello'"), "main.lua" ).call(); 
  

Fine-Grained Control of Compiling and Loading Lua

Executable LuaFunctions are created from lua code in several steps

• find the resource using the platform's ResourceFinder
• compile lua to lua bytecode using Compiler
• load lua bytecode to a Prototype using Globals.Undumper
• construct LuaClosure from Prototype with Globals using Globals.Loader

There are alternate flows when the direct lua-to-Java bytecode compiling LuaJC is used.

• compile lua to lua bytecode using Compiler or load precompiled code using Globals.Undumper
• convert lua bytecode to equivalent Java bytecode using LuaJC that implements Globals.Loader directly

Java Field

Certain public fields are provided that contain the current values of important global state:

• STDIN Current value for standard input in the laaded IoLib, if any.
• STDOUT Current value for standard output in the loaded IoLib, if any.
• STDERR Current value for standard error in the loaded IoLib, if any.
• finder Current loaded ResourceFinder, if any.
• compiler Current loaded Compiler, if any.
• undumper Current loaded Globals.Undumper, if any.
• loader Current loaded Globals.Loader, if any.

Lua Environment Variables

When using JsePlatform or JmePlatform, these environment variables are created within the Globals.

• "_G" Pointer to this Globals.
• "_VERSION" String containing the version of luaj.

Use in Multithreaded Environments

In a multi-threaded server environment, each server thread should create one Globals instance, which will be logically distinct and not interfere with each other, but share certain static immutable resources such as class data and string data.

See Also:

JsePlatform, JmePlatform, LuaValue, Compiler, Globals.Loader, Globals.Undumper, ResourceFinder, LuaC, LuaJC

Nested Class Summary

static interface	Globals.Compiler Interface for module that converts lua source text into a prototype.
static interface	Globals.Loader Interface for module that converts a Prototype into a LuaFunction with an environment.
static interface	Globals.Undumper Interface for module that loads lua binary chunk into a prototype.

Field Summary

BaseLib	baselib The BaseLib instance loaded into this Globals
Globals.Compiler	compiler The installed compiler.
DebugLib	debuglib The DebugLib instance loaded into this Globals, or null if debugging is not enabled
ResourceFinder	finder The installed ResourceFinder for looking files by name.
Globals.Loader	loader The installed loader.
PackageLib	package_ The PackageLib instance loaded into this Globals
LuaThread	running The currently running thread.
java.io.PrintStream	STDERR The current default error stream.
java.io.InputStream	STDIN The current default input stream.
java.io.PrintStream	STDOUT The current default output stream.
Globals.Undumper	undumper The installed undumper.

Fields inherited from class org.luaj.vm2.LuaTable

array, hash, hashEntries, m_metatable

Fields inherited from class org.luaj.vm2.LuaValue

ADD, CALL, CONCAT, DIV, EMPTYSTRING, ENV, EQ, FALSE, INDEX, LE, LEN, LT, METATABLE, MINUSONE, MOD, MODE, MUL, NEWINDEX, NIL, NILS, NONE, NOVALS, ONE, POW, SUB, TBOOLEAN, TFUNCTION, TINT, TLIGHTUSERDATA, TNIL, TNONE, TNUMBER, TOSTRING, TRUE, TSTRING, TTABLE, TTHREAD, TUSERDATA, TVALUE, TYPE_NAMES, UNM, ZERO

Constructor Summary

Globals()

Method Summary

Globals	checkglobals() Check that this object is a Globals object, and return it, otherwise throw an error.
Prototype	compilePrototype(java.io.InputStream stream, java.lang.String chunkname) Compile lua source from an InputStream into a Prototype.
Prototype	compilePrototype(java.io.Reader reader, java.lang.String chunkname) Compile lua source from a Reader into a Prototype.
LuaValue	load(java.io.InputStream is, java.lang.String chunkname, java.lang.String mode, LuaValue environment) Load the content form an input stream as a binary chunk or text file.
LuaValue	load(java.io.Reader reader, java.lang.String chunkname) Load the content form a reader as a text file.
LuaValue	load(java.io.Reader reader, java.lang.String chunkname, LuaTable environment) Load the content form a reader as a text file, supplying a custom environment.
LuaValue	load(java.lang.String script) Convenience function to load a string value as a script.
LuaValue	load(java.lang.String script, java.lang.String chunkname) Convenience function to load a string value as a script.
LuaValue	load(java.lang.String script, java.lang.String chunkname, LuaTable environment) Convenience function to load a string value as a script with a custom environment.
LuaValue	loadfile(java.lang.String filename) Convenience function for loading a file that is either binary lua or lua source.
Prototype	loadPrototype(java.io.InputStream is, java.lang.String chunkname, java.lang.String mode) Load lua source or lua binary from an input stream into a Prototype.
Varargs	yield(Varargs args) Function which yields the current thread.

Methods inherited from class org.luaj.vm2.LuaTable

arrayget, checktable, concat, defaultEntry, entry, eq_b, eq, get, get, getArrayLength, getHashLength, getmetatable, hashget, hashmod, hashpow2, hashset, hashSlot, inext, insert, isLargeKey, istable, keyCount, keys, len, length, next, opttable, presize, presize, rawget, rawget, rawlen, rawset, rawset, remove, set, set, setmetatable, sort, toLuaValue, type, typename, unpack, unpack, unpack, useWeakKeys, useWeakValues, wrap

Methods inherited from class org.luaj.vm2.LuaValue

add, add, add, and, arg, arg1, argerror, argerror, aritherror, aritherror, arithmt, arithmtwith, assert_, buffer, call, call, call, call, call, callmt, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checkthread, checkuserdata, checkuserdata, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eqmtcall, equals, error, get, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, initupvalue1, invoke, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isfunction, isint, isinttype, islong, isnil, isnumber, isstring, isthread, isuserdata, isuserdata, isvalidkey, lenerror, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, metatableOf, metatag, method, method, method, method, method, method, mod, mod, mod, modFrom, mul, mul, mul, narg, neg, neq_b, neq, not, onInvoke, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, optthread, optuserdata, optuserdata, optvalue, or, pow, pow, pow, powWith, powWith, raweq, raweq, raweq, raweq, raweq, rawget, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, settable, strcmp, strcmp, strongvalue, strvalue, sub, sub, sub, subargs, subFrom, subFrom, tableOf, tableOf, tableOf, tableOf, tableOf, tableOf, tailcallOf, testfor_b, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, tonumber, toshort, tostring, toString, touserdata, touserdata, typerror, unimplemented, userdataOf, userdataOf, valueOf, valueOf, valueOf, valueOf, valueOf, valueOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf, varargsOf

Methods inherited from class org.luaj.vm2.Varargs

argcheck, checkboolean, checkclosure, checkdouble, checkfunction, checkint, checkinteger, checkjstring, checklong, checknotnil, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, checkvalue, eval, isfunction, isnil, isnoneornil, isnumber, isstring, istable, isTailcall, isthread, isuserdata, isvalue, optboolean, optclosure, optdouble, optfunction, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optthread, optuserdata, optuserdata, optvalue, toboolean, tobyte, tochar, todouble, tofloat, toint, tojstring, tolong, toshort, touserdata, touserdata, type

Methods inherited from class java.lang.Object

clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

STDIN

public java.io.InputStream STDIN

The current default input stream.

STDOUT

public java.io.PrintStream STDOUT

The current default output stream.

STDERR

public java.io.PrintStream STDERR

The current default error stream.

finder

public ResourceFinder finder

The installed ResourceFinder for looking files by name.

running

public LuaThread running

The currently running thread. Should not be changed by non-library code.

baselib

public BaseLib baselib

The BaseLib instance loaded into this Globals

package_

public PackageLib package_

The PackageLib instance loaded into this Globals

debuglib

public DebugLib debuglib

The DebugLib instance loaded into this Globals, or null if debugging is not enabled

loader

public Globals.Loader loader

The installed loader.

See Also:

Globals.Loader

compiler

public Globals.Compiler compiler

The installed compiler.

See Also:

Compiler

undumper

public Globals.Undumper undumper

The installed undumper.

See Also:

Globals.Undumper

Constructor Detail

Globals

public Globals()

Method Detail

checkglobals

public Globals checkglobals()

Check that this object is a Globals object, and return it, otherwise throw an error.

Overrides:

checkglobals in class LuaValue

Returns:

this if if an instance fof Globals

loadfile

public LuaValue loadfile(java.lang.String filename)

Convenience function for loading a file that is either binary lua or lua source.

Parameters:

filename - Name of the file to load.

Returns:

LuaValue that can be call()'ed or invoke()'ed.

Throws:

LuaError - if the file could not be loaded.

load

public LuaValue load(java.lang.String script,
                     java.lang.String chunkname)

Convenience function to load a string value as a script. Must be lua source.

Parameters:

script - Contents of a lua script, such as "print 'hello, world.'"

chunkname - Name that will be used within the chunk as the source.

Returns:

LuaValue that may be executed via .call(), .invoke(), or .method() calls.

Throws:

LuaError - if the script could not be compiled.

load

public LuaValue load(java.lang.String script)

Convenience function to load a string value as a script. Must be lua source.

Parameters:

script - Contents of a lua script, such as "print 'hello, world.'"

Returns:

LuaValue that may be executed via .call(), .invoke(), or .method() calls.

Throws:

LuaError - if the script could not be compiled.

load

public LuaValue load(java.lang.String script,
                     java.lang.String chunkname,
                     LuaTable environment)

Convenience function to load a string value as a script with a custom environment. Must be lua source.

Parameters:

script - Contents of a lua script, such as "print 'hello, world.'"

chunkname - Name that will be used within the chunk as the source.

environment - LuaTable to be used as the environment for the loaded function.

Returns:

LuaValue that may be executed via .call(), .invoke(), or .method() calls.

Throws:

LuaError - if the script could not be compiled.

load

public LuaValue load(java.io.Reader reader,
                     java.lang.String chunkname)

Load the content form a reader as a text file. Must be lua source. The source is converted to UTF-8, so any characters appearing in quoted literals above the range 128 will be converted into multiple bytes.

Parameters:

reader - Reader containing text of a lua script, such as "print 'hello, world.'"

chunkname - Name that will be used within the chunk as the source.

Returns:

LuaValue that may be executed via .call(), .invoke(), or .method() calls.

Throws:

LuaError - if the script could not be compiled.

load

public LuaValue load(java.io.Reader reader,
                     java.lang.String chunkname,
                     LuaTable environment)

Load the content form a reader as a text file, supplying a custom environment. Must be lua source. The source is converted to UTF-8, so any characters appearing in quoted literals above the range 128 will be converted into multiple bytes.

Parameters:

reader - Reader containing text of a lua script, such as "print 'hello, world.'"

chunkname - Name that will be used within the chunk as the source.

environment - LuaTable to be used as the environment for the loaded function.

Returns:

LuaValue that may be executed via .call(), .invoke(), or .method() calls.

Throws:

LuaError - if the script could not be compiled.

load

public LuaValue load(java.io.InputStream is,
                     java.lang.String chunkname,
                     java.lang.String mode,
                     LuaValue environment)

Load the content form an input stream as a binary chunk or text file.

Parameters:

is - InputStream containing a lua script or compiled lua"

chunkname - Name that will be used within the chunk as the source.

mode - String containing 'b' or 't' or both to control loading as binary or text or either.

environment - LuaTable to be used as the environment for the loaded function.

loadPrototype

public Prototype loadPrototype(java.io.InputStream is,
                               java.lang.String chunkname,
                               java.lang.String mode)
                        throws java.io.IOException

Load lua source or lua binary from an input stream into a Prototype. The InputStream is either a binary lua chunk starting with the lua binary chunk signature, or a text input file. If it is a text input file, it is interpreted as a UTF-8 byte sequence.

Parameters:

is - Input stream containing a lua script or compiled lua"

chunkname - Name that will be used within the chunk as the source.

mode - String containing 'b' or 't' or both to control loading as binary or text or either.

Throws:

java.io.IOException

compilePrototype

public Prototype compilePrototype(java.io.Reader reader,
                                  java.lang.String chunkname)
                           throws java.io.IOException

Compile lua source from a Reader into a Prototype. The characters in the reader are converted to bytes using the UTF-8 encoding, so a string literal containing characters with codepoints 128 or above will be converted into multiple bytes.

Throws:

java.io.IOException

compilePrototype

public Prototype compilePrototype(java.io.InputStream stream,
                                  java.lang.String chunkname)
                           throws java.io.IOException

Compile lua source from an InputStream into a Prototype. The input is assumed to be UTf-8, but since bytes in the range 128-255 are passed along as literal bytes, any ASCII-compatible encoding such as ISO 8859-1 may also be used.

Throws:

java.io.IOException

yield

public Varargs yield(Varargs args)

Function which yields the current thread.

Parameters:

args - Arguments to supply as return values in the resume function of the resuming thread.

Returns:

Values supplied as arguments to the resume() call that reactivates this thread.