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

## org.luaj.vm2
Class LuaClosure

    java.lang.Object
      org.luaj.vm2.Varargs
          org.luaj.vm2.LuaValue
              org.luaj.vm2.LuaFunction
                  org.luaj.vm2.LuaClosure

    public class LuaClosure

extends LuaFunction

Extension of `LuaFunction` which executes lua bytecode.

A `LuaClosure` is a combination of a `Prototype` and a `LuaValue` to use as an environment for execution. Normally the `LuaValue` is a `Globals` in which case the environment will contain standard lua libraries.

There are three main ways `LuaClosure` instances are created:

- Construct an instance using `LuaClosure(Prototype, LuaValue)`
- Construct it indirectly by loading a chunk via `Globals.load(java.io.Reader, String)`
- Execute the lua bytecode `Lua.OP_CLOSURE` as part of bytecode processing

To construct it directly, the `Prototype` is typically created via a compiler such as `LuaC`:

     String script = "print( 'hello, world' )";
     InputStream is = new ByteArrayInputStream(script.getBytes());
     Prototype p = LuaC.instance.compile(is, "script");
     LuaValue globals = JsePlatform.standardGlobals();
     LuaClosure f = new LuaClosure(p, globals);
     f.call();

To construct it indirectly, the `Globals.load(java.io.Reader, String)` method may be used:

     Globals globals = JsePlatform.standardGlobals();
     LuaFunction f = globals.load(new StringReader(script), "script");
     LuaClosure c = f.checkclosure();  // This may fail if LuaJC is installed.
     c.call();

In this example, the "checkclosure()" may fail if direct lua-to-java-bytecode compiling using LuaJC is installed, because no LuaClosure is created in that case and the value returned is a `LuaFunction` but not a `LuaClosure`.

Since a `LuaClosure` is a `LuaFunction` which is a `LuaValue`, all the value operations can be used directly such as:

- `LuaValue.call()`
- `LuaValue.call(LuaValue)`
- `LuaValue.invoke()`
- `LuaValue.invoke(Varargs)`
- `LuaValue.method(String)`
- `LuaValue.method(String,LuaValue)`
- `LuaValue.invokemethod(String)`
- `LuaValue.invokemethod(String,Varargs)`
- ...

See Also:
  `LuaValue`, `LuaFunction`, `LuaValue.isclosure()`, `LuaValue.checkclosure()`, `LuaValue.optclosure(LuaClosure)`, `LoadState`, `Globals.compiler`

Field Summary
`Prototype` `p`
`UpValue[]` `upValues`

Fields inherited from class org.luaj.vm2.LuaFunction
`s_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
`LuaClosure(Prototype p, LuaValue env)` Create a closure around a Prototype with a specific environment.

Method Summary
`LuaValue` `call()` Call `this` with 0 arguments, including metatag processing, and return only the first return value.
`LuaValue` `call(LuaValue arg)` Call `this` with 1 argument, including metatag processing, and return only the first return value.
`LuaValue` `call(LuaValue arg1, LuaValue arg2)` Call `this` with 2 arguments, including metatag processing, and return only the first return value.
`LuaValue` `call(LuaValue arg1, LuaValue arg2, LuaValue arg3)` Call `this` with 3 arguments, including metatag processing, and return only the first return value.
`LuaClosure` `checkclosure()` Check that the value is a `LuaClosure` , or throw `LuaError` if not
`protected Varargs` `execute(LuaValue[] stack, Varargs varargs)`
`LuaValue` `getmetatable()` Get the metatable for this `LuaValue`
`protected LuaValue` `getUpvalue(int i)`
`Varargs` `invoke(Varargs varargs)` Call `this` with variable arguments, including metatag processing, and retain all return values in a `Varargs`.
`boolean` `isclosure()` Check if `this` is a `function` that is a closure, meaning interprets lua bytecode for its execution
`java.lang.String` `name()` Return a human-readable name for this function.
`Varargs` `onInvoke(Varargs varargs)` Callback used during tail call processing to invoke the function once.
`LuaClosure` `optclosure(LuaClosure defval)` Check that optional argument is a closure and return as `LuaClosure`
`protected void` `setUpvalue(int i, LuaValue v)`
`java.lang.String` `tojstring()` Convert to human readable String for any type.

Methods inherited from class org.luaj.vm2.LuaFunction
`checkfunction, classnamestub, isfunction, optfunction, strvalue, type, typename`

Methods inherited from class org.luaj.vm2.LuaValue

`add, add, add, and, arg, arg1, argerror, argerror, aritherror, aritherror, arithmt, arithmtwith, assert_, buffer, call, callmt, checkboolean, checkdouble, checkglobals, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eq_b, eq, eqmtcall, equals, error, get, get, get, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, inext, initupvalue1, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isint, isinttype, islong, isnil, isnumber, isstring, istable, isthread, isuserdata, isuserdata, isvalidkey, len, lenerror, length, 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, next, not, optboolean, optdouble, optint, optinteger, optjstring, optlong, optnumber, optstring, opttable, optthread, optuserdata, optuserdata, optvalue, or, pow, pow, pow, powWith, powWith, presize, raweq, raweq, raweq, raweq, raweq, rawget, rawget, rawget, rawlen, rawset, rawset, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, set, set, setmetatable, settable, strcmp, strcmp, strongvalue, sub, sub, sub, subargs, subFrom, subFrom, tableOf, tableOf, tableOf, tableOf, tableOf, tableOf, tailcallOf, testfor_b, toboolean, tobyte, tochar, todouble, tofloat, toint, 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

### p

    public final Prototype p

### upValues

    public UpValue[] upValues

Constructor Detail

### LuaClosure

    public LuaClosure(Prototype p,
                      LuaValue env)

  Create a closure around a Prototype with a specific environment. If the prototype has upvalues, the environment will be written into the first upvalue.

  Parameters:
    `p` - the Prototype to construct this Closure for.
    `env` - the environment to associate with the closure.

Method Detail

### isclosure

    public boolean isclosure()

  Description copied from class: `LuaValue`
  Check if `this` is a `function` that is a closure, meaning interprets lua bytecode for its execution

  Overrides:
    `isclosure` in class `LuaValue`
  Returns:
    true if this is a `closure`, otherwise false
  See Also:
    `LuaValue.isfunction()`, `LuaValue.checkclosure()`, `LuaValue.optclosure(LuaClosure)`, `LuaValue.TFUNCTION`

### optclosure

    public LuaClosure optclosure(LuaClosure defval)

  Description copied from class: `LuaValue`
  Check that optional argument is a closure and return as `LuaClosure`

  A `LuaClosure` is a `LuaFunction` that executes lua byteccode.

  Overrides:
    `optclosure` in class `LuaValue`
  Parameters:
    `defval` - `LuaClosure` to return if `this` is nil or none
  Returns:
    `this` cast to `LuaClosure` if a function, `defval` if nil or none, throws `LuaError` otherwise
  See Also:
    `LuaValue.checkclosure()`, `LuaValue.isclosure()`, `LuaValue.TFUNCTION`

### checkclosure

    public LuaClosure checkclosure()

  Description copied from class: `LuaValue`
  Check that the value is a `LuaClosure` , or throw `LuaError` if not

  `LuaClosure` is a subclass of `LuaFunction` that interprets lua bytecode.

  Overrides:
    `checkclosure` in class `LuaValue`
  Returns:
    `this` cast as `LuaClosure`
  See Also:
    `LuaValue.checkfunction()`, `LuaValue.optclosure(LuaClosure)`, `LuaValue.isclosure()`, `LuaValue.TFUNCTION`

### getmetatable

    public LuaValue getmetatable()

  Description copied from class: `LuaValue`
  Get the metatable for this `LuaValue`

  For `LuaTable` and `LuaUserdata` instances, the metatable returned is this instance metatable. For all other types, the class metatable value will be returned.

  Overrides:
    `getmetatable` in class `LuaFunction`
  Returns:
    metatable, or null if it there is none
  See Also:
    `LuaBoolean.s_metatable`, `LuaNumber.s_metatable`, `LuaNil.s_metatable`, `LuaFunction.s_metatable`, `LuaThread.s_metatable`

### tojstring

    public java.lang.String tojstring()

  Description copied from class: `LuaValue`
  Convert to human readable String for any type.

  Overrides:
    `tojstring` in class `LuaFunction`
  Returns:
    String for use by human readers based on type.
  See Also:
    `LuaValue.tostring()`, `LuaValue.optjstring(String)`, `LuaValue.checkjstring()`, `LuaValue.isstring()`, `LuaValue.TSTRING`

### call

    public final LuaValue call()

  Description copied from class: `LuaValue`
  Call `this` with 0 arguments, including metatag processing, and return only the first return value.

  If `this` is a `LuaFunction`, call it, and return only its first return value, dropping any others. Otherwise, look for the `LuaValue.CALL` metatag and call that.

  If the return value is a `Varargs`, only the 1st value will be returned. To get multiple values, use `LuaValue.invoke()` instead.

  To call `this` as a method call, use `LuaValue.method(LuaValue)` instead.

  Overrides:
    `call` in class `LuaValue`
  Returns:
    First return value `(this())`, or `LuaValue.NIL` if there were none.
  See Also:
    `LuaValue.call(LuaValue)`, `LuaValue.call(LuaValue,LuaValue)`, `LuaValue.call(LuaValue, LuaValue, LuaValue)`, `LuaValue.invoke()`, `LuaValue.method(String)`, `LuaValue.method(LuaValue)`

### call

    public final LuaValue call(LuaValue arg)

  Description copied from class: `LuaValue`
  Call `this` with 1 argument, including metatag processing, and return only the first return value.

  If `this` is a `LuaFunction`, call it, and return only its first return value, dropping any others. Otherwise, look for the `LuaValue.CALL` metatag and call that.

  If the return value is a `Varargs`, only the 1st value will be returned. To get multiple values, use `LuaValue.invoke()` instead.

  To call `this` as a method call, use `LuaValue.method(LuaValue)` instead.

  Overrides:
    `call` in class `LuaValue`
  Parameters:
    `arg` - First argument to supply to the called function
  Returns:
    First return value `(this(arg))`, or `LuaValue.NIL` if there were none.
  See Also:
    `LuaValue.call()`, `LuaValue.call(LuaValue,LuaValue)`, `LuaValue.call(LuaValue, LuaValue, LuaValue)`, `LuaValue.invoke(Varargs)`, `LuaValue.method(String,LuaValue)`, `LuaValue.method(LuaValue,LuaValue)`

### call

    public final LuaValue call(LuaValue arg1,
                               LuaValue arg2)

  Description copied from class: `LuaValue`
  Call `this` with 2 arguments, including metatag processing, and return only the first return value.

  If `this` is a `LuaFunction`, call it, and return only its first return value, dropping any others. Otherwise, look for the `LuaValue.CALL` metatag and call that.

  If the return value is a `Varargs`, only the 1st value will be returned. To get multiple values, use `LuaValue.invoke()` instead.

  To call `this` as a method call, use `LuaValue.method(LuaValue)` instead.

  Overrides:
    `call` in class `LuaValue`
  Parameters:
    `arg1` - First argument to supply to the called function
    `arg2` - Second argument to supply to the called function
  Returns:
    First return value `(this(arg1,arg2))`, or `LuaValue.NIL` if there were none.
  See Also:
    `LuaValue.call()`, `LuaValue.call(LuaValue)`, `LuaValue.call(LuaValue, LuaValue, LuaValue)`, `LuaValue.invoke(LuaValue, Varargs)`, `LuaValue.method(String,LuaValue,LuaValue)`, `LuaValue.method(LuaValue,LuaValue,LuaValue)`

### call

    public final LuaValue call(LuaValue arg1,
                               LuaValue arg2,
                               LuaValue arg3)

  Description copied from class: `LuaValue`
  Call `this` with 3 arguments, including metatag processing, and return only the first return value.

  If `this` is a `LuaFunction`, call it, and return only its first return value, dropping any others. Otherwise, look for the `LuaValue.CALL` metatag and call that.

  If the return value is a `Varargs`, only the 1st value will be returned. To get multiple values, use `LuaValue.invoke()` instead.

  To call `this` as a method call, use `LuaValue.method(LuaValue)` instead.

  Overrides:
    `call` in class `LuaValue`
  Parameters:
    `arg1` - First argument to supply to the called function
    `arg2` - Second argument to supply to the called function
    `arg3` - Second argument to supply to the called function
  Returns:
    First return value `(this(arg1,arg2,arg3))`, or `LuaValue.NIL` if there were none.
  See Also:
    `LuaValue.call()`, `LuaValue.call(LuaValue)`, `LuaValue.call(LuaValue, LuaValue)`, `LuaValue.invoke(LuaValue, LuaValue, Varargs)`, `LuaValue.invokemethod(String,Varargs)`, `LuaValue.invokemethod(LuaValue,Varargs)`

### invoke

    public final Varargs invoke(Varargs varargs)

  Description copied from class: `LuaValue`
  Call `this` with variable arguments, including metatag processing, and retain all return values in a `Varargs`.

  If `this` is a `LuaFunction`, call it, and return all values. Otherwise, look for the `LuaValue.CALL` metatag and call that.

  To get a particular return value, us `Varargs.arg(int)`

  To call `this` as a method call, use `LuaValue.invokemethod(LuaValue)` instead.

  Overrides:
    `invoke` in class `LuaValue`
  Parameters:
    `varargs` - Varargs containing the arguments to supply to the called function
  Returns:
    All return values as a `Varargs` instance.
  See Also:
    `LuaValue.varargsOf(LuaValue[])`, `LuaValue.call(LuaValue)`, `LuaValue.invoke()`, `LuaValue.invoke(LuaValue,Varargs)`, `LuaValue.invokemethod(String,Varargs)`, `LuaValue.invokemethod(LuaValue,Varargs)`

### onInvoke

    public final Varargs onInvoke(Varargs varargs)

  Description copied from class: `LuaValue`
  Callback used during tail call processing to invoke the function once.

  This may return a `TailcallVarargs` to be evaluated by the client.

  This should not be called directly, instead use one of the call invocation functions.

  Overrides:
    `onInvoke` in class `LuaValue`
  Parameters:
    `varargs` - the arguments to the call invocation.
  Returns:
    Varargs the return values, possible a TailcallVarargs.
  See Also:
    `LuaValue.call()`, `LuaValue.invoke()`, `LuaValue.method(LuaValue)`, `LuaValue.invokemethod(LuaValue)`

### execute

    protected Varargs execute(LuaValue[] stack,
                              Varargs varargs)

### getUpvalue

    protected LuaValue getUpvalue(int i)

### setUpvalue

    protected void setUpvalue(int i,
                              LuaValue v)

### name

    public java.lang.String name()

  Description copied from class: `LuaFunction`
  Return a human-readable name for this function. Returns the last part of the class name by default. Is overridden by LuaClosure to return the source file and line, and by LibFunctions to return the name.

  Overrides:
    `name` in class `LuaFunction`
  Returns:
    common name for this function.

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