open-autonomous-connection/luaj
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 2 Wiki Activity

Add javadoc content to source files.

Browse Source
This commit is contained in:
James Roseborough
2011-01-22 01:00:20 +00:00
parent 1a648fef56
commit 4fb425bb16
37 changed files with 1129 additions and 133 deletions
Download Patch File Download Diff File Expand all files Collapse all files

8
src/jse/org/luaj/vm2/lib/jse/CoerceJavaToLua.java
View File

@@ -1,5 +1,5 @@
/*******************************************************************************
* Copyright (c) 2009 Luaj.org. All rights reserved.
* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,11 @@ import org.luaj.vm2.LuaInteger;
import org.luaj.vm2.LuaString;
import org.luaj.vm2.LuaValue;
/**
* Helper class to coerce values from Java to lua within the luajava library.
*
* @see LuajavaLib
*/
public class CoerceJavaToLua {
public static interface Coercion {

8
src/jse/org/luaj/vm2/lib/jse/CoerceLuaToJava.java
View File

@@ -1,5 +1,5 @@
/*******************************************************************************
* Copyright (c) 2009 Luaj.org. All rights reserved.
* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -29,7 +29,11 @@ import org.luaj.vm2.LuaError;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
/**
* Helper class to coerce values from lua to Java within the luajava library.
*
* @see LuajavaLib
*/
public class CoerceLuaToJava {
public static interface Coercion {

43
src/jse/org/luaj/vm2/lib/jse/JseBaseLib.java
View File

@@ -26,16 +26,45 @@ import java.io.FileInputStream;
import java.io.IOException;
import java.io.InputStream;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.BaseLib;
import org.luaj.vm2.lib.LibFunction;
import org.luaj.vm2.lib.ResourceFinder;
/**
* Base library implementation, targeted for JSE platforms.
*
* Implements the same library functions as org.luaj.lib.BaseLib,
* but looks in the current directory for files loaded via
* loadfile(), dofile() and require().
*
* @see org.luaj.vm2.lib.jse.JseBaseLib
* Subclass of {@link BaseLib} and {@link LibFunction} which implements the lua basic library functions
* and provides a directory based {@link ResourceFinder} as the {@link #FINDER}.
* <p>
* Since JME has no file system by default, {@link BaseLib} implements
* {@link ResourceFinder} using {@link Class#getResource(String)}.
* The {@link JseBaseLib} implements {@link FINDER} by scanning the current directory
* first, then falling back to {@link Class#getResource(String)} if that fails.
* Otherwise, the behavior is the same as that of {@link BaseLib}.
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This is a direct port of the corresponding library in C.
* @see BaseLib
* @see ResourceFinder
* @see #FINDER
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.1">http://www.lua.org/manual/5.1/manual.html#5.1</a>
*/
public class JseBaseLib extends org.luaj.vm2.lib.BaseLib {
/** Construct a JSE base library instance */

34
src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
View File

@@ -30,12 +30,40 @@ import java.io.RandomAccessFile;
import org.luaj.vm2.LuaError;
import org.luaj.vm2.LuaString;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.BaseLib;
import org.luaj.vm2.lib.IoLib;
import org.luaj.vm2.lib.LibFunction;
/**
* Implementation of the lua io library for J2se using RandomAccessFile
* to implement seek.
/**
* Subclass of {@link IoLib} and therefore {@link LibFunction} which implements the lua standard {@code io}
* library for the JSE platform.
* <p>
* It uses RandomAccessFile to implement seek on files.
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseIoLib());
* _G.get("io").get("write").call(LuaValue.valueOf("hello, world\n"));
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see IoLib
* @see JmeIoLib
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.7">http://www.lua.org/manual/5.1/manual.html#5.7</a>
*/
public class JseIoLib extends IoLib {

38
src/jse/org/luaj/vm2/lib/jse/JseMathLib.java
View File

@@ -1,5 +1,5 @@
/*******************************************************************************
* Copyright (c) 2009 Luaj.org. All rights reserved.
* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -22,15 +22,39 @@
package org.luaj.vm2.lib.jse;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.MathLib;
import org.luaj.vm2.lib.LibFunction;
import org.luaj.vm2.lib.OneArgFunction;
import org.luaj.vm2.lib.TwoArgFunction;
/**
* Math library implementation for use on JSE platform.
*
* Implements all "math" functions, including platform-specific
* overrides for pow() and exp()
/**
* Subclass of {@link LibFunction} which implements the lua standard {@code math}
* library.
* <p>
* It contains all lua math functions, including those not available on the JME platform.
* See {@link org.luaj.lib.MathLib} for the exception list.
* <p>
* Typically, this library is included as part of a call to
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseMathLib());
* System.out.println( _G.get("math").get("sqrt").call( LuaValue.valueOf(2) ) );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see JseMathLib
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.6">http://www.lua.org/manual/5.1/manual.html#5.6</a>
*/
public class JseMathLib extends org.luaj.vm2.lib.MathLib {

50
src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
View File

@@ -23,18 +23,46 @@ package org.luaj.vm2.lib.jse;
import java.io.File;
import java.io.IOException;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.LibFunction;
/**
* Implementation of the lua os library for J2se.
*
* <p>Implements features specific to the J2se environment:
* <bl>
* <li>execute()</li>
* <li>remove()</li>
* <li>rename()</li>
* <li>tmpname()</li>
* </bl>
*
* @see org.luaj.vm2.lib.OsLib
* Subclass of {@link LibFunction} which implements the standard lua {@code os} library.
* <p>
* This contains more complete implementations of the following functions
* using features that are specific to JSE:
* <ul>
* <li>{@code execute()}</li>
* <li>{@code remove()}</li>
* <li>{@code rename()}</li>
* <li>{@code tmpname()}</li>
* </ul>
* <p>
* Because the nature of the {@code os} library is to encapsulate
* os-specific features, the behavior of these functions varies considerably
* from their counterparts in the C platform.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* _G.load(new JseBaseLib());
* _G.load(new PackageLib());
* _G.load(new JseOsLib());
* System.out.println( _G.get("os").get("time").call() );
* } </pre>
* Doing so will ensure the library is properly initialized
* and loaded into the globals table.
* <p>
* @see LibFunction
* @see OsLib
* @see JsePlatform
* @see JmePlatform
* @see <a href="http://www.lua.org/manual/5.1/manual.html#5.8">http://www.lua.org/manual/5.1/manual.html#5.8</a>
*/
public class JseOsLib extends org.luaj.vm2.lib.OsLib {

60
src/jse/org/luaj/vm2/lib/jse/JsePlatform.java
View File

@@ -1,5 +1,5 @@
/*******************************************************************************
* Copyright (c) 2009 Luaj.org. All rights reserved.
* Copyright (c) 2009-2011 Luaj.org. All rights reserved.
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
@@ -24,18 +24,66 @@ package org.luaj.vm2.lib.jse;
import org.luaj.vm2.compiler.LuaC;
import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaThread;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.lib.CoroutineLib;
import org.luaj.vm2.lib.DebugLib;
import org.luaj.vm2.lib.PackageLib;
import org.luaj.vm2.lib.StringLib;
import org.luaj.vm2.lib.TableLib;
/** The {@link JsePlatform} class is a convenience class to standardize
* how globals tables are initialized for the JSE platform.
* <p>
* It is used to allocate either a set of standard globals using
* {@link #standardGlobals()} or debug globals using {@link #debugGlobals()}
* <p>
* A simple example of initializing globals and using them from Java is:
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* _G.get("print").call(LuaValue.valueOf("hello, world"));
* } </pre>
* <p>
* Once globals are created, a simple way to load and run a script is:
* <pre> {@code
* LoadState.load( new FileInputStream("main.lua"), "main.lua", _G ).call();
* } </pre>
* <p>
* although {@code require} could also be used:
* <pre> {@code
* _G.get("require").call(LuaValue.valueOf("main"));
* } </pre>
* For this to succeed, the file "main.lua" must be in the current directory or a resource.
* See {@link JseBaseLib} for details on finding scripts using {@link ResourceFinder}.
* <p>
* The standard globals will contain all standard libraries plus {@code luajava}:
* <ul>
* <li>{@link JseBaseLib}</li>
* <li>{@link PackageLib}</li>
* <li>{@link TableLib}</li>
* <li>{@link StringLib}</li>
* <li>{@link CoroutineLib}</li>
* <li>{@link JseMathLib}</li>
* <li>{@link JseIoLib}</li>
* <li>{@link JseOsLib}</li>
* <li>{@link LuajavaLib}</li>
* </ul>
* In addition, the {@link LuaC} compiler is installed so lua files may be loaded in their source form.
* <p>
* The debug globals are simply the standard globals plus the {@code debug} library {@link DebugLib}.
* <p>
* The class ensures that initialization is done in the correct order,
* and that linkage is made to {@link LuaThread#setGlobals(LuaValue)}.
* @see JmePlatform
*/
public class JsePlatform {
/**
* Create a standard set of globals for JSE including all the libraries.
*
* @return Table of globals initialized with the standard JSE libraries
* @see #debugGlobals()
* @see JsePlatform
* @see JmePlatform
*/
public static LuaTable standardGlobals() {
LuaTable _G = new LuaTable();
@@ -52,7 +100,15 @@ public class JsePlatform {
LuaC.install();
return _G;
}
/** Create standard globals including the {@link debug} library.
*
* @return Table of globals initialized with the standard JSE and debug libraries
* @see #standardGlobals()
* @see JsePlatform
* @see JmePlatform
* @see DebugLib
*/
public static LuaTable debugGlobals() {
LuaTable _G = standardGlobals();
_G.load(new DebugLib());

41
src/jse/org/luaj/vm2/lib/jse/LuajavaLib.java
View File

@@ -22,10 +22,6 @@
package org.luaj.vm2.lib.jse;
/** LuaJava-like bindings to Java scripting.
*
* TODO: coerce types on way in and out, pick method base on arg count ant types.
*/
import java.lang.reflect.Array;
import java.lang.reflect.Constructor;
import java.lang.reflect.Field;
@@ -43,11 +39,48 @@ import org.luaj.vm2.LuaTable;
import org.luaj.vm2.LuaUserdata;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.Varargs;
import org.luaj.vm2.compiler.LuaC;
import org.luaj.vm2.lib.LibFunction;
import org.luaj.vm2.lib.PackageLib;
import org.luaj.vm2.lib.ThreeArgFunction;
import org.luaj.vm2.lib.TwoArgFunction;
import org.luaj.vm2.lib.VarArgFunction;
/**
* Subclass of {@link LibFunction} which implements the features of the luajava package.
* <p>
* Luajava is an approach to mixing lua and java using simple functions that bind
* java classes and methods to lua dynamically. The API is documented on the
* <a href="http://www.keplerproject.org/luajava/">luajava</a> documentation pages.
* <p>
* Typically, this library is included as part of a call to either
* {@link JsePlatform#standardGlobals()}
* <p>
* To instantiate and use it directly,
* link it into your globals table via {@link LuaValue#load(LuaValue)} using code such as:
* <pre> {@code
* LuaTable _G = new LuaTable();
* LuaThread.setGlobals(_G);
* LuaC.install();
* _G.load(new BaseLib());
* _G.load(new PackageLib());
* _G.load(new LuajavaLib());
* _G.get("loadstring").call( LuaValue.valueOf(
* "sys = luajava.bindClass('java.lang.System')\n"+
* "print ( sys:currentTimeMillis() )\n" ) ).call();
* } </pre>
* This example is not intended to be realistic - only to show how the {@link LuajavaLib}
* may be initialized by hand. In practice, the {@code luajava} library is available
* on all JSE platforms via the call to {@link JsePlatform#standardGlobals()}
* and the luajava api's are simply invoked from lua.
* <p>
* This has been implemented to match as closely as possible the behavior in the corresponding library in C.
* @see LibFunction
* @see JsePlatform
* @see JmePlatform
* @see LuaC
* @see <a href="http://www.keplerproject.org/luajava/manual.html#luareference">http://www.keplerproject.org/luajava/manual.html#luareference</a>
*/
public class LuajavaLib extends VarArgFunction {
static final int INIT = 0;

24
src/jse/org/luaj/vm2/luajc/LuaJC.java
View File

@@ -32,6 +32,30 @@ import org.luaj.vm2.Prototype;
import org.luaj.vm2.LoadState.LuaCompiler;
import org.luaj.vm2.compiler.LuaC;
/**
* Implementation of {@link LuaCompiler} which does direct
* lua-to-java-bytecode compiling.
* <p>
* This requires the bcel library to be on the class path to work as expected.
* If the library is not found, the default {@link LuaC} lua-to-lua-bytecode
* compiler will be used.
* <p>
* The compiler should be installed as part of globals initialization,
* and before any scripts or lua code is executed.
* A typical example is to install it following the globals creation,
* as in the following:
* <pre> {@code
* LuaValue _G = JsePlatform.standardGlobals();
* LuaJC.install();
* LoadState.load( new ByteArrayInputStream("print 'hello'".getBytes()), "main.lua", _G ).call();
* } </pre>
* @see LuaCompiler
* @see LuaC
* @see JsePlatform
* @see JmePlatform
* @see BaseLib
* @see LuaValue
*/
public class LuaJC implements LuaCompiler {
private static final String NON_IDENTIFIER = "[^a-zA-Z0-9_$/.\\-]";