# Globals (Luaj API)
Date: 2015-04-29

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

Copyright © 2007-2015 Luaj.org. All Rights Reserved.