From 37b759485b8b5d6852ee6e05d8fda0e03bdc22c5 Mon Sep 17 00:00:00 2001 From: James Roseborough Date: Thu, 2 Apr 2009 14:52:18 +0000 Subject: [PATCH] Update README to include documentation on debug library. --- README.html | 131 ++++++++++-------- .../org/luaj/sample/SampleJ2seMain.java | 2 + 2 files changed, 78 insertions(+), 55 deletions(-) diff --git a/README.html b/README.html index 6ad3c359..7c9ff6bd 100644 --- a/README.html +++ b/README.html @@ -31,6 +31,10 @@ Freely available under the terms of the examples · concepts +· +libraries +· +building

@@ -164,41 +168,6 @@ A working example may be found in -

Include and use the luajava library

- -

-To include the luajava library, include a line in your script such as: - -

-	require( "org.luaj.lib.j2se.Luajava" )
-
- -

-or include the following line in your startup code: - -

-	org.luaj.lib.j2se.Luajava.init( vm._G );
-
- -

-See the following example for more details: -

-	src/sample/LuajavaRunner.java
-
- -

-Because reflection is required by the implementation, this is only usable from the J2SE platform. - -

-You must include the library lib/luaj-j2se-${VER}.jar in your class path. - -

-You can try sample code that creates a simple Swing UI using: -

-	java -cp luaj-j2se-${VERS}.jar lua src/test/res/swingapp.lua
-
- -

2 - Concepts

Platforms

@@ -217,7 +186,14 @@ This platform is used to set up the basic environment for a J2ME application. The default search path is limited to the jar resources, and the math operations are limited to those supported by J2ME. + +

3 - Libraries

+

Standard Libraries

+ +Libraries are coded to closely match the behavior specified in +See standard lua documentation for details on the library API's +

The following libraries are loaded by default in J2ME and J2SE platforms: 

@@ -229,39 +205,84 @@ The following libraries are loaded by default in J2ME and J2SE platforms:
 	table
-In addition, J2SE contains these two libraries: -
+

+The following libraries are optional, but preconfigured for some platforms and tools:
+
           
 	io
-	luajava
+	debug     
+	luajava 
 

 
-See standard lua documentation for details on the library API's
+The following is not yet implemented:
+
+	os
+

+
+
Optional  Libraries

+
+
I/O Library

+The J2SE platform contains the io library by default.
 
 

-There is a partial implementation of the io for J2ME in 
+The J2ME platform has an optional, partial implementation of the io in 
 
 	src/j2me/org/luaj/lib/j2me/Cldc10IoLib.java
 

-See the sample midlet to see how it is added to a platform. 
 
-
The Luajava Library

-The luajava library implements a few functions which allow access to most classes 
-within the host J2SE runtime.  They are included as part of the standard J2SE platform.
-
-
LuaJava

-The luajava library is used to easily bind to Java classes via reflection.
-It is patterned after the original luajava project.
-
-Because J2ME does not contain a reflection API, this library cannot be made to work on J2ME, 
-and is not included by default.
-
-
Unimplemented Libraries

-The following libraries are not yet implemented:
+To install into your vm instance use (j2me only):
+
+	LuaState vm = Platform.newLuaState();
+	org.luaj.lib.j2me.Cldc10IoLib.install(vm._G);
+

+
+

+See the sample midlet int src/sample/SampleMIDlet for an example.
+
+
Debug Library

+The following library is optional:
 
-	os
 	debug
 

 
+Install from Java using:
+
+	LuaState vm = Platform.newLuaState();
+	org.luaj.lib.DebugLib.install(vm);
+

+
+or install from lua using:
+
+	require 'org.luaj.lib.DebugLib'
+

+
+The lua command line utility includes the debug library by default.
+
+
+
The Luajava Library

+The J2SE platform includes the luajava library, which simplifies binding to Java classes and methods.  
+It is patterned after the original luajava project.
+
+

+The following lua script will open a swiing frame on J2SE:
+
+	jframe = luajava.bindClass( "javax.swing.JFrame" )
+	frame = luajava.newInstance( "javax.swing.JFrame", "Texts" );
+	frame:setDefaultCloseOperation(jframe.EXIT_ON_CLOSE)
+	frame:setSize(300,400)
+	frame:setVisible(true)
+

+
+

+See a longer sample in src/test/res/swingapp.lua for details, or try running it using: 
+
+	java -cp luaj-j2se-${VERS}.jar lua src/test/res/swingapp.lua
+

+
+

+The J2ME platform does not include this library, and it cannot be made to work because of the lack of a reflection API in J2SE. 
+
+
4 - Building and Testing

+
 
Building the jars

 An ant file is included in the root directory which builds the libraries by default.
 
diff --git a/src/sample/org/luaj/sample/SampleJ2seMain.java b/src/sample/org/luaj/sample/SampleJ2seMain.java
index c23bbeea..a28b3f10 100644
--- a/src/sample/org/luaj/sample/SampleJ2seMain.java
+++ b/src/sample/org/luaj/sample/SampleJ2seMain.java
@@ -8,6 +8,8 @@ public class SampleJ2seMain {
 		String script = (args.length>0? args[0]: "src/test/res/swingapp.lua");
 		Platform.setInstance( new J2sePlatform() );
 		LuaState vm = Platform.newLuaState();
+		// uncomment to install the debug library
+		// org.luaj.lib.DebugLib.install(vm);
 		org.luaj.compiler.LuaC.install();
 		vm.getglobal( "dofile" );
 		vm.pushstring( script );