Java: Add Herb Java JNI Bindings (#766)

This pull request adds Java bindings for Herb using the JNI (Java Native
Interface), allowing Java applications to parse and analyze ERB
templates with the same implementation as the native C, Ruby
C-Extension, C++ Emscripten WASM and the C++ Node.js NAPI bindings.

Building the Java bindings requires Java and a C compiler:

```bash
cd java
make
```

Once built, you can use the `herb-java` CLI tool:

#### **`herb-java version`**
```
herb java v0.7.5, libprism v1.6.0, libherb v0.7.5 (Java JNI)
```

#### **`herb-java lex examples/test.html.erb`**
```js
#<Herb::Token type="TOKEN_HTML_TAG_START" value="<" range=[0, 1] start=(1:0) end=(1:1)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="h1" range=[1, 3] start=(1:1) end=(1:3)>
#<Herb::Token type="TOKEN_WHITESPACE" value=" " range=[3, 4] start=(1:3) end=(1:4)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="class" range=[4, 9] start=(1:4) end=(1:9)>
#<Herb::Token type="TOKEN_EQUALS" value="=" range=[9, 10] start=(1:9) end=(1:10)>
#<Herb::Token type="TOKEN_QUOTE" value="\"" range=[10, 11] start=(1:10) end=(1:11)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="title" range=[11, 16] start=(1:11) end=(1:16)>
#<Herb::Token type="TOKEN_QUOTE" value="\"" range=[16, 17] start=(1:16) end=(1:17)>
#<Herb::Token type="TOKEN_HTML_TAG_END" value=">" range=[17, 18] start=(1:17) end=(1:18)>
#<Herb::Token type="TOKEN_ERB_START" value="<%=" range=[18, 21] start=(1:18) end=(1:21)>
#<Herb::Token type="TOKEN_ERB_CONTENT" value=" content " range=[21, 30] start=(1:21) end=(1:30)>
#<Herb::Token type="TOKEN_ERB_END" value="%>" range=[30, 32] start=(1:30) end=(1:32)>
#<Herb::Token type="TOKEN_HTML_TAG_START_CLOSE" value="</" range=[32, 34] start=(1:32) end=(1:34)>
#<Herb::Token type="TOKEN_IDENTIFIER" value="h1" range=[34, 36] start=(1:34) end=(1:36)>
#<Herb::Token type="TOKEN_HTML_TAG_END" value=">" range=[36, 37] start=(1:36) end=(1:37)>
#<Herb::Token type="TOKEN_NEWLINE" value="\n" range=[37, 38] start=(1:37) end=(2:0)>
#<Herb::Token type="TOKEN_EOF" value="<EOF>" range=[38, 38] start=(2:0) end=(2:0)>
```

#### **`herb-java parse examples/test.html.erb`**
```js
@ DocumentNode (location: (1:0)-(2:0))
└── children: (2 items)
    ├── @ HTMLElementNode (location: (1:0)-(1:37))
    │   ├── open_tag:
    │   │   └── @ HTMLOpenTagNode (location: (1:0)-(1:18))
    │   │       ├── tag_opening: "<" (location: (1:0)-(1:1))
    │   │       ├── tag_name: "h1" (location: (1:1)-(1:3))
    │   │       ├── tag_closing: ">" (location: (1:17)-(1:18))
    │   │       ├── children: (1 item)
    │   │       │   └── @ HTMLAttributeNode (location: (1:4)-(1:17))
    │   │       │       ├── name:
    │   │       │       │   └── @ HTMLAttributeNameNode (location: (1:4)-(1:9))
    │   │       │       │       └── children: (1 item)
    │   │       │       │           └── @ LiteralNode (location: (1:4)-(1:9))
    │   │       │       │               └── content: "class"
    │   │       │       │
    │   │       │       ├── equals: "=" (location: (1:9)-(1:10))
    │   │       │       └── value:
    │   │       │           └── @ HTMLAttributeValueNode (location: (1:10)-(1:17))
    │   │       │               ├── open_quote: "\"" (location: (1:10)-(1:11))
    │   │       │               ├── children: (1 item)
    │   │       │               │   └── @ LiteralNode (location: (1:11)-(1:16))
    │   │       │               │       └── content: "title"
    │   │       │               ├── close_quote: "\"" (location: (1:16)-(1:17))
    │   │       │               └── quoted: true
    │   │       └── is_void: false
    │   │
    │   ├── tag_name: "h1" (location: (1:1)-(1:3))
    │   ├── body: (1 item)
    │   │   └── @ ERBContentNode (location: (1:18)-(1:32))
    │   │       ├── tag_opening: "<%=" (location: (1:18)-(1:21))
    │   │       ├── content: " content " (location: (1:21)-(1:30))
    │   │       ├── tag_closing: "%>" (location: (1:30)-(1:32))
    │   │       ├── parsed: true
    │   │       └── valid: true
    │   ├── close_tag:
    │   │   └── @ HTMLCloseTagNode (location: (1:32)-(1:37))
    │   │       ├── tag_opening: "</" (location: (1:32)-(1:34))
    │   │       ├── tag_name: "h1" (location: (1:34)-(1:36))
    │   │       ├── children: []
    │   │       └── tag_closing: ">" (location: (1:36)-(1:37))
    │   │
    │   ├── is_void: false
    │   └── source: ""
    │
    └── @ HTMLTextNode (location: (1:37)-(2:0))
        └── content: "\n"
```

Resolves #648

Author: marcoroth

.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());
+    }
+  }
+}
+```
+:::