org.luaj.vm2.lib
Class LibFunction

java.lang.Object
  extended by org.luaj.vm2.Varargs
      extended by org.luaj.vm2.LuaValue
          extended by org.luaj.vm2.LuaFunction
              extended by org.luaj.vm2.lib.LibFunction
Direct Known Subclasses:
OneArgFunction, ThreeArgFunction, TwoArgFunction, VarArgFunction, ZeroArgFunction

public abstract class LibFunction
extends LuaFunction

Subclass of LuaFunction common to Java functions exposed to lua.

To provide for common implementations in JME and JSE, library functions are typically grouped on one or more library classes and an opcode per library function is defined and used to key the switch to the correct function within the library.

Since lua functions can be called with too few or too many arguments, and there are overloaded LuaValue.call() functions with varying number of arguments, a Java function exposed in lua needs to handle the argument fixup when a function is called with a number of arguments differs from that expected.

To simplify the creation of library functions, there are 5 direct subclasses to handle common cases based on number of argument values and number of return return values.

To be a Java library that can be loaded via require, it should have a public constructor that returns a LuaValue that, when executed, initializes the library.

For example, the following code will implement a library called "hyperbolic" with two functions, "sinh", and "cosh":

 import org.luaj.vm2.LuaValue;
 import org.luaj.vm2.lib.*;
 
 public class hyperbolic extends TwoArgFunction {

	public hyperbolic() {}

	public LuaValue call(LuaValue modname, LuaValue env) {
		LuaValue library = tableOf();
		library.set( "sinh", new sinh() );
		library.set( "cosh", new cosh() );
		env.set( "hyperbolic", library );
		return library;
	}

	static class sinh extends OneArgFunction {
		public LuaValue call(LuaValue x) {
			return LuaValue.valueOf(Math.sinh(x.checkdouble()));
		}
	}
	
	static class cosh extends OneArgFunction {
		public LuaValue call(LuaValue x) {
			return LuaValue.valueOf(Math.cosh(x.checkdouble()));
		}
	}
}
The default constructor is used to instantiate the library in response to require 'hyperbolic' statement, provided it is on Java"s class path. This instance is then invoked with 2 arguments: the name supplied to require(), and the environment for this function. The library may ignore these, or use them to leave side effects in the global environment, for example. In the previous example, two functions are created, 'sinh', and 'cosh', and placed into a global table called 'hyperbolic' using the supplied 'env' argument.

To test it, a script such as this can be used:

 local t = require('hyperbolic')
 print( 't', t )
 print( 'hyperbolic', hyperbolic )
 for k,v in pairs(t) do
 	print( 'k,v', k,v )
 end
 print( 'sinh(.5)', hyperbolic.sinh(.5) )
 print( 'cosh(.5)', hyperbolic.cosh(.5) )
 

It should produce something like:

 t	table: 3dbbd23f
 hyperbolic	table: 3dbbd23f
 k,v	cosh	function: 3dbbd128
 k,v	sinh	function: 3dbbd242
 sinh(.5)	0.5210953
 cosh(.5)	1.127626
 

See the source code in any of the library functions such as BaseLib or TableLib for other examples.


Field Summary
protected  java.lang.String name
          The common name for this function, useful for debugging.
protected  int opcode
          User-defined opcode to differentiate between instances of the library function class.
 
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
protected LibFunction()
          Default constructor for use by subclasses
 
Method Summary
protected  void bind(LuaValue env, java.lang.Class factory, java.lang.String[] names)
          Bind a set of library functions.
protected  void bind(LuaValue env, java.lang.Class factory, java.lang.String[] names, int firstopcode)
          Bind a set of library functions, with an offset
 LuaValue call()
          Call this with 0 arguments, including metatag processing, and return only the first return value.
 LuaValue call(LuaValue a)
          Call this with 1 argument, including metatag processing, and return only the first return value.
 LuaValue call(LuaValue a, LuaValue b)
          Call this with 2 arguments, including metatag processing, and return only the first return value.
 LuaValue call(LuaValue a, LuaValue b, LuaValue c)
          Call this with 3 arguments, including metatag processing, and return only the first return value.
 LuaValue call(LuaValue a, LuaValue b, LuaValue c, LuaValue d)
           
 Varargs invoke(Varargs args)
          Call this with variable arguments, including metatag processing, and retain all return values in a Varargs.
protected static LuaValue[] newupe()
          Java code generation utility to allocate storage for upvalue, leave it empty
protected static LuaValue[] newupl(LuaValue v)
          Java code generation utility to allocate storage for upvalue, initialize with value
protected static LuaValue[] newupn()
          Java code generation utility to allocate storage for upvalue, initialize with nil
 java.lang.String tojstring()
          Convert to human readable String for any type.
 
Methods inherited from class org.luaj.vm2.LuaFunction
checkfunction, classnamestub, getmetatable, isfunction, name, 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, checkclosure, 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, isclosure, 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, onInvoke, optboolean, optclosure, 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

opcode

protected int opcode
User-defined opcode to differentiate between instances of the library function class.

Subclass will typicall switch on this value to provide the specific behavior for each function.


name

protected java.lang.String name
The common name for this function, useful for debugging.

Binding functions initialize this to the name to which it is bound.

Constructor Detail

LibFunction

protected LibFunction()
Default constructor for use by subclasses

Method Detail

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

bind

protected void bind(LuaValue env,
                    java.lang.Class factory,
                    java.lang.String[] names)
Bind a set of library functions.

An array of names is provided, and the first name is bound with opcode = 0, second with 1, etc.

Parameters:
env - The environment to apply to each bound function
factory - the Class to instantiate for each bound function
names - array of String names, one for each function.
See Also:
bind(LuaValue, Class, String[], int)

bind

protected void bind(LuaValue env,
                    java.lang.Class factory,
                    java.lang.String[] names,
                    int firstopcode)
Bind a set of library functions, with an offset

An array of names is provided, and the first name is bound with opcode = firstopcode, second with firstopcode+1, etc.

Parameters:
env - The environment to apply to each bound function
factory - the Class to instantiate for each bound function
names - array of String names, one for each function.
firstopcode - the first opcode to use
See Also:
bind(LuaValue, Class, String[])

newupe

protected static LuaValue[] newupe()
Java code generation utility to allocate storage for upvalue, leave it empty


newupn

protected static LuaValue[] newupn()
Java code generation utility to allocate storage for upvalue, initialize with nil


newupl

protected static LuaValue[] newupl(LuaValue v)
Java code generation utility to allocate storage for upvalue, initialize with value


call

public 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 LuaValue call(LuaValue a)
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:
a - 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 LuaValue call(LuaValue a,
                     LuaValue b)
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:
a - First argument to supply to the called function
b - 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 LuaValue call(LuaValue a,
                     LuaValue b,
                     LuaValue c)
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:
a - First argument to supply to the called function
b - Second argument to supply to the called function
c - 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)

call

public LuaValue call(LuaValue a,
                     LuaValue b,
                     LuaValue c,
                     LuaValue d)

invoke

public Varargs invoke(Varargs args)
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:
args - 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)


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