org.luaj.vm2.lib
Class LibFunction

java.lang.Object
  org.luaj.vm2.Varargs
      org.luaj.vm2.LuaValue
          org.luaj.vm2.LuaFunction
              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.

• ZeroArgFunction
• OneArgFunction
• TwoArgFunction
• ThreeArgFunction
• VarArgFunction

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.OneArgFunction;
 
 public class hyperbolic extends OneArgFunction {

	public hyperbolic() {}

	public LuaValue call(LuaValue libname) {
		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 Javas class path. This instance is then invoked with the name supplied to require() as the only argument, and library should initialized whatever global data it needs to and place it into the environment if needed. In this case, it creates two function, 'sinh', and 'cosh', and puts them into a global table called 'hyperbolic.' It placed the library table into the globals via the LuaFunction.env local variable which corresponds to the globals that apply when the library is loaded.

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

env, s_metatable

Fields inherited from class org.luaj.vm2.LuaValue

ADD, CALL, CONCAT, DIV, EMPTYSTRING, 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
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, getfenv, getmetatable, isfunction, optfunction, setfenv, 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, call, call, call, callmt, checkboolean, checkclosure, checkdouble, checkint, checkinteger, checkjstring, checklong, checkmetatag, checknotnil, checknumber, checknumber, checkstring, checktable, checkthread, checkuserdata, checkuserdata, checkvalidkey, compareerror, compareerror, comparemt, concat, concat, concatmt, concatTo, concatTo, concatTo, div, div, div, divInto, eq_b, eq, eqmtcall, equals, error, get, get, get, getn, gettable, gt_b, gt_b, gt_b, gt, gt, gt, gteq_b, gteq_b, gteq_b, gteq, gteq, gteq, illegal, inext, invoke, invoke, invoke, invoke, invoke, invoke, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, invokemethod, isboolean, isclosure, isint, isinttype, islong, isnil, isnumber, isstring, istable, isthread, isuserdata, isuserdata, isweaknil, len, lenerror, length, listOf, listOf, load, lt_b, lt_b, lt_b, lt, lt, lt, lteq_b, lteq_b, lteq_b, lteq, lteq, lteq, 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, rawset, rawset, rawset, rawset, rawset, rawset, rawset, rawsetlist, set, set, set, set, set, set, set, setmetatable, settable, strcmp, strcmp, strongkey, strongvalue, strvalue, sub, sub, sub, 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, subargs, 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 LuaValue

Returns:

String for use by human readers based on type.

See Also:

LuaValue.tostring(), LuaValue.optjstring(String), LuaValue.checkjstring(), LuaValue.isstring(), 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