|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectorg.luaj.vm2.Varargs
org.luaj.vm2.LuaValue
org.luaj.vm2.LuaFunction
org.luaj.vm2.lib.LibFunction
public abstract class LibFunction
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.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 |
---|
protected int opcode
Subclass will typicall switch on this value to provide the specific behavior for each function.
protected java.lang.String name
Binding functions initialize this to the name to which it is bound.
Constructor Detail |
---|
protected LibFunction()
Method Detail |
---|
public java.lang.String tojstring()
LuaValue
tojstring
in class LuaFunction
LuaValue.tostring()
,
LuaValue.optjstring(String)
,
LuaValue.checkjstring()
,
LuaValue.isstring()
,
LuaValue.TSTRING
protected void bind(LuaValue env, java.lang.Class factory, java.lang.String[] names)
An array of names is provided, and the first name is bound with opcode = 0, second with 1, etc.
env
- The environment to apply to each bound functionfactory
- the Class to instantiate for each bound functionnames
- array of String names, one for each function.bind(LuaValue, Class, String[], int)
protected void bind(LuaValue env, java.lang.Class factory, java.lang.String[] names, int firstopcode)
An array of names is provided, and the first name is bound
with opcode = firstopcode
, second with firstopcode+1
, etc.
env
- The environment to apply to each bound functionfactory
- the Class to instantiate for each bound functionnames
- array of String names, one for each function.firstopcode
- the first opcode to usebind(LuaValue, Class, String[])
protected static LuaValue[] newupe()
protected static LuaValue[] newupn()
protected static LuaValue[] newupl(LuaValue v)
public LuaValue call()
LuaValue
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.
call
in class LuaValue
(this())
, or LuaValue.NIL
if there were none.LuaValue.call(LuaValue)
,
LuaValue.call(LuaValue,LuaValue)
,
LuaValue.call(LuaValue, LuaValue, LuaValue)
,
LuaValue.invoke()
,
LuaValue.method(String)
,
LuaValue.method(LuaValue)
public LuaValue call(LuaValue a)
LuaValue
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.
call
in class LuaValue
a
- First argument to supply to the called function
(this(arg))
, or LuaValue.NIL
if there were none.LuaValue.call()
,
LuaValue.call(LuaValue,LuaValue)
,
LuaValue.call(LuaValue, LuaValue, LuaValue)
,
LuaValue.invoke(Varargs)
,
LuaValue.method(String,LuaValue)
,
LuaValue.method(LuaValue,LuaValue)
public LuaValue call(LuaValue a, LuaValue b)
LuaValue
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.
call
in class LuaValue
a
- First argument to supply to the called functionb
- Second argument to supply to the called function
(this(arg1,arg2))
, or LuaValue.NIL
if there were none.LuaValue.call()
,
LuaValue.call(LuaValue)
,
LuaValue.call(LuaValue, LuaValue, LuaValue)
,
LuaValue.invoke(LuaValue, Varargs)
,
LuaValue.method(String,LuaValue,LuaValue)
,
LuaValue.method(LuaValue,LuaValue,LuaValue)
public LuaValue call(LuaValue a, LuaValue b, LuaValue c)
LuaValue
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.
call
in class LuaValue
a
- First argument to supply to the called functionb
- Second argument to supply to the called functionc
- Second argument to supply to the called function
(this(arg1,arg2,arg3))
, or LuaValue.NIL
if there were none.LuaValue.call()
,
LuaValue.call(LuaValue)
,
LuaValue.call(LuaValue, LuaValue)
,
LuaValue.invoke(LuaValue, LuaValue, Varargs)
,
LuaValue.invokemethod(String,Varargs)
,
LuaValue.invokemethod(LuaValue,Varargs)
public LuaValue call(LuaValue a, LuaValue b, LuaValue c, LuaValue d)
public Varargs invoke(Varargs args)
LuaValue
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.
invoke
in class LuaValue
args
- Varargs containing the arguments to supply to the called function
Varargs
instance.LuaValue.varargsOf(LuaValue[])
,
LuaValue.call(LuaValue)
,
LuaValue.invoke()
,
LuaValue.invoke(LuaValue,Varargs)
,
LuaValue.invokemethod(String,Varargs)
,
LuaValue.invokemethod(LuaValue,Varargs)
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES All Classes | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |