Java: Add Herb Java JNI Bindings

.envrc

@@ -4,3 +4,4 @@ export PATH="$PWD/javascript/packages/formatter/bin:$PATH"
 export PATH="$PWD/javascript/packages/language-server/bin:$PATH"
 export PATH="$PWD/javascript/packages/highlighter/bin:$PATH"
 export PATH="$PWD/javascript/packages/stimulus-lint/bin:$PATH"
+export PATH="$PWD/java/bin:$PATH"

.gitattributes

@@ -1,8 +1,11 @@
 # Templates
 templates/**/*.c.erb linguist-language=C
+templates/**/*.cpp.erb linguist-language=C++
 templates/**/*.h.erb linguist-language=C
+templates/**/*.java.erb linguist-language=Java
+templates/**/*.js.erb linguist-language=JavaScript
 templates/**/*.rb.erb linguist-language=Ruby
-templates/**/*.cpp.erb linguist-language=C++
+templates/**/*.ts.erb linguist-language=TypeScript
 
 # Template-generated RBS files
 sig/**/*.rbs linguist-generated

.github/labeler.yml

@@ -36,6 +36,12 @@ typescript:
       - '**/javascript/**/*.ts'
       - '**/javascript/**/*.ts.erb'
 
+java:
+  - changed-files:
+    - any-glob-to-any-file:
+      - '**/*.java'
+      - '**/*.java.erb'
+
 ruby:
   - changed-files:
     - any-glob-to-any-file:

.github/workflows/java.yml

@@ -0,0 +1,53 @@
+name: Java
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: 'temurin'
+          java-version: '17'
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          bundler-cache: true
+
+      - name: Render Templates
+        run: bundle exec rake templates
+
+      - name: Compile Herb
+        run: bundle exec rake make
+
+      - name: Build JNI library
+        run: make jni
+        working-directory: java
+
+      - name: Compile Java classes
+        run: make java
+        working-directory: java
+
+      - name: Run tests
+        run: ./run_tests.sh
+        working-directory: java
+
+      - name: Test CLI version command
+        run: ./bin/herb-java version
+        working-directory: java

.gitignore

@@ -89,9 +89,17 @@ ext/herb/error_helpers.c
 ext/herb/error_helpers.h
 ext/herb/nodes.c
 ext/herb/nodes.h
+java/error_helpers.c
+java/error_helpers.h
+java/nodes.c
+java/nodes.h
+java/org/herb/ast/Errors.java
+java/org/herb/ast/Nodes.java
+java/org/herb/ast/NodeVisitor.java
+java/org/herb/ast/Visitor.java
 javascript/packages/core/src/errors.ts
-javascript/packages/core/src/nodes.ts
 javascript/packages/core/src/node-type-guards.ts
+javascript/packages/core/src/nodes.ts
 javascript/packages/core/src/visitor.ts
 javascript/packages/node/extension/error_helpers.cpp
 javascript/packages/node/extension/error_helpers.h
@@ -100,8 +108,8 @@ javascript/packages/node/extension/nodes.h
 lib/herb/ast/nodes.rb
 lib/herb/errors.rb
 lib/herb/visitor.rb
-sig/serialized_ast_nodes.rbs
 sig/serialized_ast_errors.rbs
+sig/serialized_ast_nodes.rbs
 src/ast_nodes.c
 src/ast_pretty_print.c
 src/errors.c
@@ -114,6 +122,10 @@ wasm/error_helpers.h
 wasm/nodes.cpp
 wasm/nodes.h
 
+# Java Build Artifacts
+java/target/
+java/.java_compiled
+
 # NX Monorepo
 .nx/
 .nx/cache

docs/.vitepress/config/theme.mts

@@ -90,6 +90,14 @@ const defaultSidebar = [
           { text: "Reference", link: "/bindings/javascript/reference" },
         ],
       },
+      {
+        text: "Java",
+        collapsed: false,
+        items: [
+          { text: "Installation", link: "/bindings/java/" },
+          { text: "Reference", link: "/bindings/java/reference" },
+        ],
+      },
       { text: "WebAssembly", link: "/projects/webassembly" },
     ],
   },

docs/docs/bindings/java/index.md

@@ -0,0 +1,93 @@
+---
+outline: deep
+---
+
+# Herb Java Bindings
+
+Herb provides official Java bindings through JNI (Java Native Interface) to the C library, allowing you to parse HTML+ERB in Java projects with native performance.
+
+> [!TIP] More Language Bindings
+> Herb also has bindings for:
+> - [Ruby](/bindings/ruby/)
+> - [JavaScript/Node.js](/bindings/javascript/)
+
+## Installation
+
+### Prerequisites
+
+Ensure you have Java installed:
+
+:::code-group
+```shell
+java -version
+```
+:::
+
+### Build from Source
+
+Clone the repository and build the Java bindings:
+
+:::code-group
+```shell
+git clone https://github.com/your-org/herb.git
+cd herb/java
+make templates
+make jni
+make java
+```
+:::
+
+This creates the native library (`libherb_jni.dylib` on macOS, `.so` on Linux).
+
+### Setting Up Your Project
+
+Add the compiled classes to your classpath and ensure the native library is in your `java.library.path`.
+
+## Getting Started
+
+### Basic Example
+
+Here's a simple example of parsing HTML+ERB:
+
+:::code-group
+```java
+import org.herb.Herb;
+import org.herb.ParseResult;
+
+public class Example {
+  public static void main(String[] args) {
+    String source = "<h1><%= user.name %></h1>";
+
+    ParseResult result = Herb.parse(source);
+
+    if (result.getValue() != null) {
+      System.out.println(result.getValue().treeInspect());
+    }
+  }
+}
+```
+:::
+
+### Lexing Example
+
+You can also tokenize HTML+ERB source:
+
+:::code-group
+```java
+import org.herb.Herb;
+import org.herb.LexResult;
+import org.herb.Token;
+
+public class LexExample {
+  public static void main(String[] args) {
+    String source = "<h1><%= user.name %></h1>";
+
+    LexResult result = Herb.lex(source);
+
+    for (Token token : result.getTokens()) {
+      System.out.println(token.inspect());
+    }
+  }
+}
+```
+:::