Updated documentation

gudzpoz · Mar 29, 2024 · 8c0fb97 · 8c0fb97
1 parent b9b06ed
commit 8c0fb97
Show file tree

Hide file tree

Showing 11 changed files with 868 additions and 1,281 deletions.
diff --git a/README.md b/README.md
@@ -2,8 +2,8 @@
 
 [![Build Status](https://github.com/gudzpoz/luajava/actions/workflows/build-natives.yml/badge.svg)](https://github.com/gudzpoz/luajava/actions/workflows/build-natives.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
-![Codecov](https://img.shields.io/codecov/c/github/gudzpoz/luajava?label=Coverage)
-![Java 8](https://img.shields.io/badge/Java-8-brown)
+[![Codecov](https://img.shields.io/codecov/c/github/gudzpoz/luajava?label=Coverage)](https://app.codecov.io/gh/gudzpoz/luajava/)
+[![Java 8](https://img.shields.io/badge/Java-8-brown)](https://www.oracle.com/java/technologies/java8.html)
 [![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/party.iroiro.luajava/luajava?server=https%3A%2F%2Fs01.oss.sonatype.org&label=Nexus&color=pink)](https://s01.oss.sonatype.org/content/repositories/snapshots/party/iroiro/luajava/)
 [![Maven Central](https://img.shields.io/maven-central/v/party.iroiro.luajava/luajava?color=blue&label=Maven%20Central)](https://mvnrepository.com/search?q=party.iroiro.luajava)
 
@@ -31,7 +31,7 @@ This is yet another fork of [the original LuaJava](https://github.com/jasonsanto
 
 > LuaJava is a scripting tool for Java. The goal of this tool is to allow scripts written in Lua to manipulate components developed in Java. LuaJava allows Java components to be accessed from Lua using the same syntax that is used for accessing Lua's native objects, without any need for declarations or any kind of preprocessing.
 >
-> LuaJava also allows Java to implement an interface using Lua. This way any interface can be implemented in Lua and passed as parameter to any method, and when called, the equivalent function will be called in Lua, and it's result passed back to Java.
+> LuaJava also allows any Java interface to get implemented in Lua and passed as parameter to any method, and when called, the equivalent function will be called in Lua, the result passed back to Java.
 >
 > LuaJava is available under the same license as Lua 5.1, that is, it can be used at no cost for both academic and commercial purposes.
 
@@ -43,24 +43,25 @@ since this library is more or less just a thin wrapper and requires some basic u
 
 <div style="display:flex;justify-content:center">
 
-| Lua 5.1 | Lua 5.2 | Lua 5.3 | Lua 5.4 |   LuaJIT    |
-|:-------:|:-------:|:-------:|:-------:|:-----------:|
-|  5.1.5  |  5.2.4  |  5.3.6  |  5.4.6  | [`0d313b2`] |
+| Lua 5.1 | Lua 5.2 | Lua 5.3 | Lua 5.4 | LuaJIT      | LuaJ     |
+|:-------:|:-------:|:-------:|:-------:|:-----------:|:--------:|
+| 5.1.5   | 5.2.4   | 5.3.6   | 5.4.6   | [`0d313b2`] | [A fork] |
 
 </div>
 
-
 [`0d313b2`]: https://github.com/LuaJIT/LuaJIT/commits/0d313b243194a0b8d2399d8b549ca5a0ff234db5
 
-Supported Lua versions: Lua 5.1, Lua 5.2, Lua 5.3, Lua 5.4 and LuaJIT.
+[A fork]: https://github.com/wagyourtail/luaj
+
+Supported Lua versions: Lua 5.1, Lua 5.2, Lua 5.3, Lua 5.4, LuaJ and LuaJIT.
 
-Supported platforms: **Windows**, **Linux**, **MacOS**, **Android**, **iOS**. Compiled against both ARM and x32/x64. Binaries are not yet tested for iOS.
+Supported platforms: **Windows**, **Linux**, **MacOS** and **Android**. Compiled against both ARM and x32/x64. Binaries are not yet tested for iOS.
 
-Compiled natives are available for most common platforms. Check out [LuaJava Platforms](https://gudzpoz.github.io/luajava/#platforms) for a platform matrix.
+Compiled natives are available for most common platforms. Check out [LuaJava Platforms](https://gudzpoz.github.io/luajava/#platforms) for a platform matrix. LuaJ bindings do not need native binaries and should run on all platforms theoretically.
 
 ### Artifacts
 
-To include LuaJava into your project, you need to include two artifacts, one for the Java bindings, the other for the compiled native binaries.
+To include LuaJava into your project, you need to include two artifacts, one for the Java bindings, the other for the compiled native binaries. (For LuaJ bindings, you don't need the latter one.)
 
 ```groovy
 // Example: LuaJIT with Desktop natives

diff --git a/android/android-test/src/androidTest/java/party/iroiro/luajava/AndroidLuaTest.java b/android/android-test/src/androidTest/java/party/iroiro/luajava/AndroidLuaTest.java
@@ -49,4 +49,5 @@ public void luaJTest() {
         try (LuaJ L = new LuaJ()) {
             new LuaTestSuite<>(L, LuaJit::new).test();
         }
+    }
 }
diff --git a/docs/.vuepress/components/Matrix.vue b/docs/.vuepress/components/Matrix.vue
@@ -10,7 +10,7 @@
 <script setup>
 import { ref } from 'vue'
 const groupId = 'party.iroiro.luajava'
-const version = '3.4.1'
+const version = '3.5.0'
 
 const notAvailable = {
   luajit: {
@@ -25,6 +25,7 @@ const luaVersions = {
   lua53: 'Lua 5.3',
   lua54: 'Lua 5.4',
   luajit: 'LuaJIT',
+  luaj: 'LuaJ',
 }
 
 const platform = ref('Desktop')
@@ -65,7 +66,7 @@ function lines(lua, platform, line) {
     const native = natives[platform]
     return `${line(groupId, 'luajava', version, null)}
 ${line(groupId, lua, version, null)}
-${native.map(n => line(groupId, lua + '-platform', version, n, 'runtime')).join('\n')}`
+${lua === 'luaj' ? '' : native.map(n => line(groupId, lua + '-platform', version, n, 'runtime')).join('\n')}`
   }
 }
 </script>

diff --git a/docs/api.md b/docs/api.md
@@ -465,7 +465,7 @@ assert(max(1.2, 2.3) == 2.3)
 :::
 
 If you would like to access an overridden default method from a proxy object,
-you may also use
+you may also use:
 
 ```lua
 iter1 = java.proxy('java.util.Iterator', {})
@@ -486,3 +486,11 @@ iter = java.proxy('java.util.Iterator', iterImpl)
 -- Calls the implemented `remove`, which then calls the default one
 iter:remove()
 ```
+
+::: warning
+
+Calling default methods is not available with LuaJ bindings,
+since the Java reflection does not provide a way to do so.
+(We use JNI functions to achieve this within binary bindings.)
+
+:::
diff --git a/docs/console.md b/docs/console.md
@@ -6,7 +6,7 @@ The jar bundles desktop natives with it, so you should be about to play around w
 
 <ClientOnly><Asciinema :file="$withBase('/example.cast')" /></ClientOnly>
 
-`Lua Version` can be any of `5.1`, `5.2`, `5.3`, `5.4` or `jit`.
+`Lua Version` can be any of `5.1`, `5.2`, `5.3`, `5.4`, `luaj` or `jit`.
 
 ## Built-In Examples
 
@@ -33,4 +33,3 @@ Usage: <main class> [-t] [-l=<lua>] [-f=<file> | -e=<expression>]
   -l, --lua=<lua>           Specify the Lua version
   -t, --test                Run built-in tests
 ```
-
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -17,7 +17,7 @@ So you will need both to get LuaJava to work correctly. Basically, using Maven C
 
 - The `groupId` is `party.iroiro.luajava`.
 - The Java interface is `party.iroiro.luajava:luajava`.
-- The Lua specific bridging artifacts are `lua5N` (`lua51` `lua52` ...) or `luajit`.
+- The Lua specific bridging artifacts are `lua5N` (`lua51` `lua52` ...) or `luajit` or `luaj`.
 - The natives has `artifactId` like `lua5N-platform` (`lua51` `lua52` ...) or `luajit-platform`.
 
 However, there are different native artifacts for different platforms, each with a different `classifier`:

diff --git a/docs/index.md b/docs/index.md
@@ -14,8 +14,10 @@ description: LuaJava, a scripting tool for Java
 [![Java 8](https://img.shields.io/badge/Java-8-brown)](https://www.oracle.com/java/technologies/java8.html)
 [![Sonatype Nexus (Snapshots)](https://img.shields.io/nexus/s/party.iroiro.luajava/luajava?server=https%3A%2F%2Fs01.oss.sonatype.org&label=Nexus&color=pink)](https://s01.oss.sonatype.org/content/repositories/snapshots/party/iroiro/luajava/)
 [![Maven Central](https://img.shields.io/maven-central/v/party.iroiro.luajava/luajava?color=blue&label=Maven%20Central)](https://mvnrepository.com/search?q=party.iroiro.luajava)
+
 [![Build Status](https://github.com/gudzpoz/luajava/actions/workflows/docs.yml/badge.svg)](https://github.com/gudzpoz/luajava/actions/workflows/docs.yml)
 [![Document Version](https://img.shields.io/github/package-json/v/gudzpoz/luajava?filename=docs%2Fpackage.json&label=Documentation)](https://gudzpoz.github.io/luajava/)
+
 [![Tests: macOS on M1](https://img.shields.io/bitrise/ace86394e12a32ad/main?label=macOS%20on%20M1&token=t-lcEHLpUl_xT-CeJYzagg)](https://app.bitrise.io/app/ace86394e12a32ad)
 [![Tests: Linux on arm64](https://img.shields.io/circleci/build/github/gudzpoz/luajava/main?label=Linux%20on%20arm64)](https://app.circleci.com/pipelines/github/gudzpoz/luajava)
 
@@ -25,13 +27,13 @@ img + span svg.external-link-icon {
 }
 </style>
 
-Yet another fork of [the original LuaJava](https://github.com/jasonsantos/luajava):
-
-LuaJava is a scripting tool for Java. The goal of this tool is to allow scripts written in Lua to manipulate components developed in Java. LuaJava allows Java components to be accessed from Lua using the same syntax that is used for accessing Lua's native objects, without any need for declarations or any kind of preprocessing.
+This is yet another fork of [the original LuaJava](https://github.com/jasonsantos/luajava).
 
-LuaJava also allows any Java interface to get implemented in Lua and passed as parameter to any method, and when called, the equivalent function will be called in Lua, the result passed back to Java.
-
-LuaJava is available under the same license as Lua 5.1, that is, it can be used at no cost for both academic and commercial purposes.
+> LuaJava is a scripting tool for Java. The goal of this tool is to allow scripts written in Lua to manipulate components developed in Java. LuaJava allows Java components to be accessed from Lua using the same syntax that is used for accessing Lua's native objects, without any need for declarations or any kind of preprocessing.
+>
+> LuaJava also allows any Java interface to get implemented in Lua and passed as parameter to any method, and when called, the equivalent function will be called in Lua, the result passed back to Java.
+>
+> LuaJava is available under the same license as Lua 5.1, that is, it can be used at no cost for both academic and commercial purposes.
 
 ::: tip
 Try it out with [a pre-built console](./console.md)!
@@ -51,34 +53,36 @@ I try to keep up with the most recent version of Lua, that is, [the latest offic
 
 <div style="display:flex;justify-content:center">
 
-| Lua 5.1 | Lua 5.2 | Lua 5.3 | Lua 5.4 |   LuaJIT    |
-|:-------:|:-------:|:-------:|:-------:|:-----------:|
-|  5.1.5  |  5.2.4  |  5.3.6  |  5.4.6  | [`0d313b2`] |
+| Lua 5.1 | Lua 5.2 | Lua 5.3 | Lua 5.4 | LuaJIT      | LuaJ     |
+|:-------:|:-------:|:-------:|:-------:|:-----------:|:--------:|
+| 5.1.5   | 5.2.4   | 5.3.6   | 5.4.6   | [`0d313b2`] | [A fork] |
 
 </div>
 
 [`0d313b2`]: https://github.com/LuaJIT/LuaJIT/commits/0d313b243194a0b8d2399d8b549ca5a0ff234db5
 
+[A fork]: https://github.com/wagyourtail/luaj
+
 [^jit]: LuaJIT no longer creates new releases. See [Project status · Issue #665](https://github.com/LuaJIT/LuaJIT/issues/665#issuecomment-784452583) for an explanation.
 
 ## Platforms
 
-Thanks to [jnigen](https://github.com/libgdx/gdx-jnigen), we have built Lua natives for almost all common platforms, readily available on [Maven Central](https://mvnrepository.com/search?q=party.iroiro.luajava). [^android]
+Thanks to [jnigen](https://github.com/libgdx/gdx-jnigen), we have built Lua natives for almost all common platforms, readily available on [Maven Central](https://mvnrepository.com/search?q=party.iroiro.luajava). [^android] [^luaj]
 
 <script setup>
-const columns = ['Lua 5.1', 'Lua 5.2', 'Lua 5.3', 'Lua 5.4', 'LuaJIT'];
+const columns = ['Lua 5.1', 'Lua 5.2', 'Lua 5.3', 'Lua 5.4', 'LuaJIT', 'LuaJ'];
 const android = 'Android <sup><a href="#fn2">[2]</a></sup>';
 const matrix = {
-  'Linux (x86_64)':   [2, 2, 2, 2, 2],
-  'Linux (x86)':      [1, 1, 1, 1, 1],
-  'Linux (ARM)':      [1, 1, 1, 1, 1],
-  'Linux (ARM64)':    [2, 2, 2, 2, 2],
-  'Windows (x86)':    [1, 1, 1, 1, 1],
-  'Windows (x86_64)': [2, 2, 2, 2, 2],
-  'MacOS (x86_64)':   [2, 2, 2, 2, 2],
-  'MacOS (ARM64)':    [2, 2, 2, 2, 2],
-  [android]:          [2, 2, 2, 2, 2],
-  'iOS':              [1, 1, 1, 1, 0],
+  'Linux (x86_64)':   [2, 2, 2, 2, 2, 2],
+  'Linux (x86)':      [1, 1, 1, 1, 1, 1],
+  'Linux (ARM)':      [1, 1, 1, 1, 1, 1],
+  'Linux (ARM64)':    [2, 2, 2, 2, 2, 2],
+  'Windows (x86)':    [1, 1, 1, 1, 1, 1],
+  'Windows (x86_64)': [2, 2, 2, 2, 2, 2],
+  'MacOS (x86_64)':   [2, 2, 2, 2, 2, 2],
+  'MacOS (ARM64)':    [2, 2, 2, 2, 2, 2],
+  [android]:          [2, 2, 2, 2, 2, 2],
+  'iOS':              [1, 1, 1, 1, 0, 1],
 };
 const classes = ['unsupported', 'available', 'tested'];
 </script>
@@ -136,3 +140,5 @@ ul li {
 [^android]: Android is available on many platforms, and we provide natives for `armeabi-v7a` `arm64-v8a` `x86` `x86_64`.
             It is tested against API levels 21, 24, 27, 30 and 33 on `x86_64` architectures
             (and on `x86` if a `default` emulator image is available) (and against my own phone of API level 30 on `arm64-v8a`).
+
+[^luaj]: Since LuaJ is written in Java, it should theoretically run on all platforms that supports Java.
diff --git a/docs/jsr223.md b/docs/jsr223.md
@@ -33,13 +33,13 @@ By default, the JSR 223 provider finds an available Lua implementation and use t
 party.iroiro.luajava.lua54.Lua54
 party.iroiro.luajava.lua53.Lua53
 party.iroiro.luajava.lua52.Lua52
+party.iroiro.luajava.luaj.LuaJ
 party.iroiro.luajava.luajit.LuaJit
 party.iroiro.luajava.lua51.Lua51
 ```
 
-If you want one of them instead, specify the system property `luajava.jsr-223`: `54` `53` `52` `jit` or `51`:
+If you want one of them instead, specify the system property `luajava.jsr-223`: `54` `53` `52` `jit` `luaj` or `51`:
 
 ```java
 System.setProperty("luajava.jsr-223", "jit");
 ```
-