Supply environment as extra argument when loading functions.

README.html

@@ -16,7 +16,7 @@
 Getting Started with LuaJ
 
 </h1>
-James Roseborough, Ian Farmer, Version 3.0-alpha1
+James Roseborough, Ian Farmer, Version 3.0-alpha2
 <p>
 <small>
 Copyright &copy; 2009-2012 Luaj.org.
@@ -117,7 +117,7 @@ in comparison with the standard C distribution.
 	<td>16.794</td>
 	<td>11.274</td>
 	<td>Java</td>
-	<td>java -cp luaj-jse-3.0-alpha1.jar;bcel-5.2.jar lua <b>-b</b> fannkuch.lua 10</td></tr>
+	<td>java -cp luaj-jse-3.0-alpha2.jar;bcel-5.2.jar lua <b>-b</b> fannkuch.lua 10</td></tr>
 <tr valign="top">
 	<td></td>
 	<td></td>
@@ -127,7 +127,7 @@ in comparison with the standard C distribution.
 	<td>36.894</td>
 	<td>15.163</td>
 	<td></td>
-	<td>java -cp luaj-jse-3.0-alpha1.jar lua -n fannkuch.lua 10</td></tr>
+	<td>java -cp luaj-jse-3.0-alpha2.jar lua -n fannkuch.lua 10</td></tr>
 <tr valign="top">
 	<td>lua</td>
 	<td>5.1.4</td>
@@ -183,7 +183,7 @@ It is also faster than Java-lua implementations Jill, Kahlua, and Mochalua for a
 From the main distribution directory line type:
 
 <pre>
-	java -cp lib/luaj-jse-3.0-alpha1.jar lua examples/lua/hello.lua
+	java -cp lib/luaj-jse-3.0-alpha2.jar lua examples/lua/hello.lua
 </pre>
 
 <p>
@@ -195,7 +195,7 @@ You should see the following output:
 To see how luaj can be used to acccess most Java API's including swing, try:
 
 <pre>
-	java -cp lib/luaj-jse-3.0-alpha1.jar lua examples/lua/swingapp.lua
+	java -cp lib/luaj-jse-3.0-alpha2.jar lua examples/lua/swingapp.lua
 </pre>
 
 <h2>Compile lua source to lua bytecode</h2>
@@ -204,8 +204,8 @@ To see how luaj can be used to acccess most Java API's including swing, try:
 From the main distribution directory line type:
 
 <pre>
-	java -cp lib/luaj-jse-3.0-alpha1.jar luac examples/lua/hello.lua
-	java -cp lib/luaj-jse-3.0-alpha1.jar lua luac.out
+	java -cp lib/luaj-jse-3.0-alpha2.jar luac examples/lua/hello.lua
+	java -cp lib/luaj-jse-3.0-alpha2.jar lua luac.out
 </pre>
 
 <p>
@@ -219,8 +219,8 @@ Luaj can compile lua sources or binaries directly to java bytecode if the bcel l
 
 <pre>
 	ant bcel-lib
-	java -cp &quot;lib/luaj-jse-3.0-alpha1.jar;lib/bcel-5.2.jar&quot; luajc -s examples/lua -d . hello.lua
-	java -cp &quot;lib/luaj-jse-3.0-alpha1.jar;.&quot; lua -l hello
+	java -cp &quot;lib/luaj-jse-3.0-alpha2.jar;lib/bcel-5.2.jar&quot; luajc -s examples/lua -d . hello.lua
+	java -cp &quot;lib/luaj-jse-3.0-alpha2.jar;.&quot; lua -l hello
 </pre>
 
 <p>
@@ -231,7 +231,7 @@ but the compiled classes must be in the class path at runtime, unless runtime ji
 <p>
 Lua scripts can also be run directly in this mode without precompiling using the <em>lua</em> command with the <b><em>-b</em></b> option and providing the <em>bcel</em> library in the class path:
 <pre>
-	java -cp &quot;lib/luaj-jse-3.0-alpha1.jar;lib/bcel-5.2.jar&quot; lua -b examples/lua/hello.lua
+	java -cp &quot;lib/luaj-jse-3.0-alpha2.jar;lib/bcel-5.2.jar&quot; lua -b examples/lua/hello.lua
 </pre>
 
 
@@ -256,7 +256,7 @@ A simple example may be found in
 </pre>
 
 <p>
-You must include the library <b>lib/luaj-jse-3.0-alpha1.jar</b> in your class path.
+You must include the library <b>lib/luaj-jse-3.0-alpha2.jar</b> in your class path.
 
 <h2>Run a script in a MIDlet</h2>
 
@@ -283,7 +283,7 @@ A simple example may be found in
 </pre>
 
 <p>
-You must include the library <b>lib/luaj-jme-3.0-alpha1.jar</b> in your midlet jar.
+You must include the library <b>lib/luaj-jme-3.0-alpha2.jar</b> in your midlet jar.
 
 <p>
 An ant script to build and run the midlet is in
@@ -311,7 +311,7 @@ The standard use of JSR-223 scripting engines may be used:
 All standard aspects of script engines including compiled statements should be supported.
 
 <p>
-You must include the library <b>lib/luaj-jse-3.0-alpha1.jar</b> in your class path.
+You must include the library <b>lib/luaj-jse-3.0-alpha2.jar</b> in your class path.
 
 <p>
 A working example may be found in
@@ -323,7 +323,7 @@ To compile and run it using Java 1.6 or higher:
 
 <pre>
 	javac examples/jse/ScriptEngineSample.java
-	java -cp &quot;lib/luaj-jse-3.0-alpha1.jar;examples/jse&quot; ScriptEngineSample
+	java -cp &quot;lib/luaj-jse-3.0-alpha2.jar;examples/jse&quot; ScriptEngineSample
 </pre>
 
 <h2>Excluding the lua bytecode compiler</h2>
@@ -487,7 +487,7 @@ The following lua script will open a swing frame on Java SE:
 See a longer sample in <em>examples/lua/swingapp.lua</em> for details, including a simple animation loop, rendering graphics, mouse and key handling, and image loading. 
 Or try running it using: 
 <pre>
-	java -cp lib/luaj-jse-3.0-alpha1.jar lua examples/lua/swingapp.lua
+	java -cp lib/luaj-jse-3.0-alpha2.jar lua examples/lua/swingapp.lua
 </pre>
 
 <p>
@@ -574,11 +574,11 @@ Each of these functions has an abstract method that must be implemented,
 and argument fixup is done automatically by the classes as each Java function is invoked.
 
 <p>
-For example, to implement a &quot;hello, world&quot; function, we could supply:
+An example of a function with no arguments but a useful return value might be:
 <pre>
-	pubic class hello extends ZeroArgFunction {
+	pubic class hostname extends ZeroArgFunction {
 		public LuaValue call() {
-			env.get("print").call(valueOf("hello, world"));
+			return valueOf(java.net.InetAddress.getLocalHost().getHostName());
 		}
 	}
 </pre>
@@ -589,20 +589,90 @@ by the instantiating object whenever default loading is used.
 <p>
 Calling this function from lua could be done by:
 <pre> 
-	require( 'hello' )()
+	local hostname = require( 'hostname' )
 </pre>
 
 while calling this function from Java would look like:
 <pre> 
-	new hello().call();
+	new hostname().call();
 </pre>
 
 Note that in both the lua and Java case, extra arguments will be ignored, and the function will be called.  
 Also, no virtual machine instance is necessary to call the function. 
 To allow for arguments, or return multiple values, extend one of the other base classes. 
+
+<h2>Libraries of Java Functions</h2>
+When require() is called, it will first attempt to load the module as a Java class that implements LuaFunction.  
+To succeed, the following requirements must be met:
+<ul>
+<li>The class must be on the class path with name, <em>modname</em>.</li>
+<li>The class must have a public default constructor.</li>
+<li>The class must inherit from LuaFunction.</li>
+</ul>
+
+<p>
+If luaj can find a class that meets these critera, it will instantiate it, cast it to <em>LuaFunction</em> 
+then call() the instance with two arguments: 
+the <em>modname</em> used in the call to require(), and the environment for that function.  
+The Java may use these values however it wishes. A typical case is to create named functions 
+in the environment that can be called from lua. 
+
+<p>
+A complete example of Java code for a simple toy library is in <a href="examples/jse/hyperbolic.java">examples/jse/hyperbolic.java</a> 
+<pre>
+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()));
+		}
+	}
+}
+</pre>
+
+In this case the call to require invokes the library itself to initialize it.  The library implementation 
+puts entries into a table, and stores this table in the environment.
+
+<p>
+The lua script used to load and test it is in <a href="examples/lua/hyperbolicapp.lua">examples/lua/hyperbolicapp.lua</a>
+<pre>
+	require 'hyperbolic'
+
+	print('hyperbolic', hyperbolic)
+	print('hyperbolic.sinh', hyperbolic.sinh)
+	print('hyperbolic.cosh', hyperbolic.cosh)
+
+	print('sinh(0.5)', hyperbolic.sinh(0.5))
+	print('cosh(0.5)', hyperbolic.cosh(0.5))
+</pre>
+
+For this example to work the code in <em>hyperbolic.java</em> must be compiled and put on the class path.
  
 <h2>Closures</h2>
-Closures still exist in this framework, but are optional, and are only used to implement lua bytecode execution.  
+Closures still exist in this framework, but are optional, and are only used to implement lua bytecode execution, 
+and is generally not directly manipulated by the user of luaj.
+<p>
+See the <a href="http://luaj.sourceforge.net/api/3.0/org/luaj/vm2/LuaClosure.html">org.luaj.vm2.LuaClosure</a> 
+javadoc for details on using that class directly. 
 
 <h1>6 - <a name="6">Parser</a></h1>
 
@@ -712,11 +782,13 @@ and LuaForge:
 <tr valign="top"><td>&nbsp;&nbsp;<b>2.0</b></td><td><ul>
 <li>Initial release of 2.0 version </li>  
 </ul></td></tr>
+
 <tr valign="top"><td>&nbsp;&nbsp;<b>2.0.1</b></td><td><ul>
 <li>Improve correctness of singleton construction related to static initialization </li>
 <li>Fix nan-related error in constant folding logic that was failing on some JVMs </li>
 <li>JSR-223 fixes: add META-INF/services entry in jse jar, improve bindings implementation </li>
 </ul></td></tr>
+
 <tr valign="top"><td>&nbsp;&nbsp;<b>2.0.2</b></td><td><ul>
 <li>JSR-223 bindings change: non Java-primitives will now be passed as LuaValue </li> 
 <li>JSR-223 enhancement: allow both ".lua" and "lua" as extensions in getScriptEngine() </li>
@@ -725,16 +797,28 @@ and LuaForge:
 <li>Enhance javadoc, put it <a href="docs/api/index.html">in distribution</a> and <a href="http://luaj.sourceforge.net/api/3.0/index.html">on line</a></li>
 <li>Major refactor of luajava type coercion logic, improve method selection.</li> 
 <li>Add lib/luaj-sources-2.0.2.jar for easier integration into an IDE such as Netbeans </li>
-<tr valign="top"><td>&nbsp;&nbsp;<b>3.0-alpha1</b></td><td><ul>
+
+<tr valign="top"><td>&nbsp;&nbsp;<b>2.0.3</b></td><td><ul>
 <li>Improve coroutine state logic including let unreferenced coroutines be garbage collected </li>
 <li>Fix lua command vararg values passed into main script to match what is in global arg table </li>
 <li>Add arithmetic metatag processing when left hand side is a number and right hand side has metatable </li>
 <li>Fix load(func) when mutiple string fragments are supplied by calls to func </li>
 <li>Allow access to public members of private inner classes where possible </li>
-<li>Add line and column info to org.luaj.vm2.ast parse tree elements generated using LuaParser </li>
+<li>Turn on error reporting in LuaParser so line numbers ar available in ParseException </li>
+<li>Improve compatibility of table.remove() </li>
+<li>Disallow base library setfenv() calls on Java functions </li>
+
+<tr valign="top"><td>&nbsp;&nbsp;<b>3.0-alpha1</b></td><td><ul>
+<li>Convert internal and external API's to match lua 5.2.x environment changes </li>
+<li>Add bit32 library </li>
+<li>Add explicit Globals object to manage global state, especially to imrpove thread safety </li>
 <li>Drop support for lua source to java surce (lua2java) in favor of direct java bytecode output (luajc) </li>
 <li>Remove compatibility functions like table.getn(), table.maxn(), table.foreach(), and math.log10() </li>
 <li>Add ability to create runnable jar file from lua script with sample build file build-app.xml </li>
+
+<tr valign="top"><td>&nbsp;&nbsp;<b>3.0-alpha2</b></td><td><ul>
+<li>Supply environment as second argument to LibFunction when loading via require() </li>
+
 </ul></td></tr>
 </table></td></tr></table>