Extractor: Add extract_ruby_options across all language bindings

docs/docs/bindings/java/reference.md

@@ -14,6 +14,7 @@ The `Herb` class provides the following static methods:
 * `Herb.parse(source)`
 * `Herb.parse(source, options)`
 * `Herb.extractRuby(source)`
+* `Herb.extractRuby(source, options)`
 * `Herb.extractHTML(source)`
 * `Herb.version()`
 * `Herb.herbVersion()`
@@ -154,10 +155,104 @@ String source = "<p>Hello <%= user.name %></p>";
 
 String ruby = Herb.extractRuby(source);
 System.out.println(ruby);
-// Output: "             user.name       "
+// Output: "             user.name  ;    "
 ```
 :::
 
+### `Herb.extractRuby(String source, ExtractRubyOptions options)`
+
+Extract Ruby with custom options.
+
+#### Default behavior
+
+By default, the output is position-preserving with semicolons:
+
+:::code-group
+```java
+import org.herb.Herb;
+
+String source = "<% x = 1 %> <% y = 2 %>";
+String ruby = Herb.extractRuby(source);
+
+System.out.println(ruby);
+// Output: "   x = 1  ;    y = 2  ;"
+```
+:::
+
+#### Without semicolons
+
+:::code-group
+```java
+import org.herb.Herb;
+import org.herb.ExtractRubyOptions;
+
+String source = "<% x = 1 %> <% y = 2 %>";
+ExtractRubyOptions options = ExtractRubyOptions.create().semicolons(false);
+String ruby = Herb.extractRuby(source, options);
+
+System.out.println(ruby);
+// Output: "   x = 1       y = 2   "
+```
+:::
+
+#### Including ERB comments
+
+:::code-group
+```java
+import org.herb.Herb;
+import org.herb.ExtractRubyOptions;
+
+String source = "<%# comment %>\n<% code %>";
+ExtractRubyOptions options = ExtractRubyOptions.create().comments(true);
+String ruby = Herb.extractRuby(source, options);
+
+System.out.println(ruby);
+// Output: "  # comment   \n   code  ;"
+```
+:::
+
+#### Without position preservation
+
+Use `preservePositions(false)` for readable output where each ERB tag is placed on its own line:
+
+:::code-group
+```java
+import org.herb.Herb;
+import org.herb.ExtractRubyOptions;
+
+String source = "<%# comment %><%= something %>";
+ExtractRubyOptions options = ExtractRubyOptions.create().preservePositions(false).comments(true);
+String ruby = Herb.extractRuby(source, options);
+
+System.out.println(ruby);
+// Output: "# comment \n something "
+```
+:::
+
+### `ExtractRubyOptions`
+
+The `ExtractRubyOptions` class provides fluent configuration:
+
+```java
+public class ExtractRubyOptions {
+  public ExtractRubyOptions semicolons(boolean value);
+  public ExtractRubyOptions comments(boolean value);
+  public ExtractRubyOptions preservePositions(boolean value);
+
+  public static ExtractRubyOptions create();
+}
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `semicolons` | `true` | Add ` ;` at the end of each ERB tag to separate statements |
+| `comments` | `false` | Include ERB comments (`<%# %>`) in the output |
+| `preservePositions` | `true` | Maintain character positions by padding with whitespace |
+
+> [!TIP]
+> Use `preservePositions(false)` when you need readable Ruby output.
+> Use `preservePositions(true)` (default) when you need accurate error position mapping.
+
 ### `Herb.extractHTML(String source)`
 
 The `extractHTML` method extracts only the HTML parts of an HTML document with embedded Ruby.

docs/docs/bindings/javascript/reference.md

@@ -42,7 +42,7 @@ Learn more on [how to install and load the NPM packages](/bindings/javascript/#i
 - **`Herb.lexFile(path: string): LexResult`**
 - **`Herb.parse(source: string): ParseResult`**
 - **`Herb.parseFile(path: string): ParseResult`**
-- **`Herb.extractRuby(source: string): string`**
+- **`Herb.extractRuby(source: string, options?: ExtractRubyOptions): string`**
 - **`Herb.extractHTML(source: string): string`**
 - **`Herb.version: string`**
 
@@ -134,7 +134,7 @@ console.log(result)
 
 Herb allows you to extract either Ruby or HTML from mixed content.
 
-### `Herb.extractRuby(source)`
+### `Herb.extractRuby(source, options?)`
 
 The `Herb.extractRuby` method allows you to extract only the Ruby parts of an HTML document with embedded Ruby.
 
@@ -148,10 +148,66 @@ const source = "<p>Hello <%= user.name %></p>"
 const ruby = Herb.extractRuby(source)
 
 console.log(ruby);
-// Outputs: "             user.name       "
+// Outputs: "             user.name  ;    "
 ```
 :::
 
+#### Options
+
+```typescript
+interface ExtractRubyOptions {
+  semicolons?: boolean        // default: true
+  comments?: boolean          // default: false
+  preserve_positions?: boolean // default: true
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `semicolons` | `boolean` | `true` | Add ` ;` at the end of each ERB tag to separate statements |
+| `comments` | `boolean` | `false` | Include ERB comments (`<%# %>`) in the output |
+| `preserve_positions` | `boolean` | `true` | Maintain character positions by padding with whitespace |
+
+#### Examples
+
+**Default behavior** (position-preserving with semicolons):
+
+```js
+const source = "<% x = 1 %> <% y = 2 %>"
+
+Herb.extractRuby(source)
+// => "   x = 1  ;    y = 2  ;"
+```
+
+**Without semicolons:**
+
+```js
+Herb.extractRuby(source, { semicolons: false })
+// => "   x = 1       y = 2   "
+```
+
+**Including ERB comments:**
+
+```js
+const source = "<%# comment %>\n<% code %>"
+
+Herb.extractRuby(source, { comments: true })
+// => "  # comment   \n   code  ;"
+```
+
+**Without position preservation** (readable output, each tag on its own line):
+
+```js
+const source = "<%# comment %><%= something %>"
+
+Herb.extractRuby(source, { preserve_positions: false, comments: true })
+// => "# comment \n something "
+```
+
+> [!TIP]
+> Use `preserve_positions: false` when you need readable Ruby output.
+> Use `preserve_positions: true` (default) when you need accurate error position mapping.
+
 ### `Herb.extractHTML(source)`
 
 The `Herb.extractHTML` method allows you to extract only the HTML parts of an HTML document with embedded Ruby.

docs/docs/bindings/ruby/reference.md

@@ -118,7 +118,7 @@ Herb.parse_file("./index.html.erb").value
 
 ## Extracting Code
 
-### `Herb.extract_ruby(source)`
+### `Herb.extract_ruby(source, **options)`
 
 The `Herb.extract_ruby` method allows you to extract only the Ruby parts of an HTML document with embedded Ruby.
 
@@ -127,10 +127,58 @@ The `Herb.extract_ruby` method allows you to extract only the Ruby parts of an H
 source = %(<p>Hello <%= user.name %></p>)
 
 Herb.extract_ruby(source)
-# => "             user.name       "
+# => "             user.name  ;    "
 ```
 :::
 
+#### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `semicolons` | `Boolean` | `true` | Add ` ;` at the end of each ERB tag to separate statements |
+| `comments` | `Boolean` | `false` | Include ERB comments (`<%# %>`) in the output |
+| `preserve_positions` | `Boolean` | `true` | Maintain character positions by padding with whitespace |
+
+#### Examples
+
+**Default behavior** (position-preserving with semicolons):
+
+```ruby
+source = "<% x = 1 %> <% y = 2 %>"
+
+Herb.extract_ruby(source)
+# => "   x = 1  ;    y = 2  ;"
+```
+
+**Without semicolons:**
+
+```ruby
+Herb.extract_ruby(source, semicolons: false)
+# => "   x = 1       y = 2   "
+```
+
+**Including ERB comments:**
+
+```ruby
+source = "<%# comment %>\n<% code %>"
+
+Herb.extract_ruby(source, comments: true)
+# => "  # comment   \n   code  ;"
+```
+
+**Without position preservation** (readable output, each tag on its own line):
+
+```ruby
+source = "<%# comment %><%= something %>"
+
+Herb.extract_ruby(source, preserve_positions: false, comments: true)
+# => "# comment \n something "
+```
+
+> [!TIP]
+> Use `preserve_positions: false` when you need readable Ruby output.
+> Use `preserve_positions: true` (default) when you need accurate error position mapping.
+
 ### `Herb.extract_html(source)`
 
 The `Herb.extract_html` method allows you to extract only the HTML parts of an HTML document with embedded Ruby.