https://github.com/hind-sagar-biswas/java-hypertext-preprocessor
A powerful, flexible template engine for Java applications. Inspired by PHP and modern template engines like Jinja2 and Blade, JHP provides an elegant syntax for embedding dynamic content in your HTML templates.
https://github.com/hind-sagar-biswas/java-hypertext-preprocessor
antlr4 hypertext-preprocessor maven preprocessor
Last synced: 6 months ago
JSON representation
A powerful, flexible template engine for Java applications. Inspired by PHP and modern template engines like Jinja2 and Blade, JHP provides an elegant syntax for embedding dynamic content in your HTML templates.
- Host: GitHub
- URL: https://github.com/hind-sagar-biswas/java-hypertext-preprocessor
- Owner: hind-sagar-biswas
- License: mit
- Created: 2025-10-04T19:11:48.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-10-04T19:40:55.000Z (6 months ago)
- Last Synced: 2025-10-04T21:23:08.810Z (6 months ago)
- Topics: antlr4, hypertext-preprocessor, maven, preprocessor
- Language: Java
- Homepage:
- Size: 126 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Java Hypertext Preprocessor (JHP)
[](https://github.com/hind-sagar-biswas/java-hypertext-preprocessor/packages)
[](https://www.oracle.com/java/)
[](LICENSE)
[](https://github.com/hind-sagar-biswas/java-hypertext-preprocessor/releases)
A powerful, flexible template engine for Java applications. Inspired by PHP and modern template engines like Jinja2 and Blade, JHP provides an elegant syntax for embedding dynamic content in your HTML templates.
## Features
- **Intuitive Syntax** - Clean, readable template syntax with `{{ }}` for output and `{% %}` for logic
- **HTML Escaping** - Automatic HTML escaping by default to prevent XSS attacks
- **Control Structures** - Full support for if/else, for, foreach, and while loops
- **Template Includes** - Modular templates with include directives
- **Built-in Functions** - Common string and utility functions out of the box
- **Extensible** - Easy to add custom functions
- **Thread-Safe** - Built for concurrent environments
- **Template Caching** - Automatic AST caching for improved performance
- **Flexible Error Handling** - Multiple modes for handling runtime issues
## Quick Start
### Installation
Add the dependency to your `pom.xml`:
```xml
com.hindbiswas.jhp
jhp
1.0.0
```
The artifact is available on [Maven Central](https://search.maven.org/artifact/com.hindbiswas.jhp/jhp).
### Basic Usage
```java
import com.hindbiswas.jhp.*;
import com.hindbiswas.jhp.engine.*;
// Create engine
Settings settings = Settings.builder()
.base("/path/to/templates")
.build();
FunctionLibrary lib = new FunctionLibrary();
JhpEngine engine = new JhpEngine(settings, lib);
// Prepare context
Context ctx = new Context();
ctx.add("name", "Alice");
ctx.add("age", 25);
// Render template
String output = engine.render("welcome.jhp", ctx);
```
**Template (welcome.jhp):**
```html
Hello {{ name }}!
{% if (age >= 18) %}
You are an adult.
{% else %}
You are a minor.
{% endif %}
```
## Template Syntax
### Output Variables
```html
{{ variable }}
{{{ rawHtml }}}
```
### Control Structures
```html
{% if (condition) %}
Content
{% elseif (otherCondition) %}
Other content
{% else %}
Default content
{% endif %}
{% for (i = 0; i < 10; i++) %}
Item {{ i }}
{% endfor %}
{% foreach (item in items) %}
{% endforeach %}
{% include 'header.jhp' %}
```
### Functions
```html
{{ touppercase(name) }}
{{ tolowercase(email) }}
{{ trim(input) }}
{{ len(items) }}
{{ now() }}
```
## Documentation
Comprehensive documentation is available in the [`docs/`](docs/) directory:
- [Installation Guide](docs/installation.md)
- [Getting Started](docs/getting-started.md)
- [Template Syntax](docs/template-syntax.md)
- [Control Structures](docs/control-structures.md)
- [Functions](docs/functions.md)
- [Context & Variables](docs/context-variables.md)
- [Configuration](docs/configuration.md)
- [Advanced Usage](docs/advanced-usage.md)
- [API Reference](docs/api-reference.md)
- [Examples](docs/examples.md)
## Building from Source
```bash
# Clone the repository
git clone https://github.com/hind-sagar-biswas/java-hypertext-preprocessor.git
cd java-hypertext-preprocessor
# Build with Maven
mvn clean install
# Run tests
mvn test
```
## Requirements
- Java 25 or higher (Java 24 supported)
- Maven 3.6+
- ANTLR 4.13.2 (automatically managed)
## Testing
The project includes comprehensive unit tests using JUnit Jupiter:
```bash
mvn test
```
**Test Coverage:**
- 88 unit tests
- Context and variable management
- Settings and configuration
- Function library (built-in and custom)
- Template rendering and integration
- AST node structures
## Examples
### Web Application
```java
@GetMapping("/profile/{username}")
public ResponseEntity profile(@PathVariable String username) {
User user = userService.findByUsername(username);
Context ctx = new Context();
ctx.add("user", user.toMap());
String html = engine.render("profile.jhp", ctx);
return ResponseEntity.ok().contentType(MediaType.TEXT_HTML).body(html);
}
```
### Email Templates
```java
public void sendWelcomeEmail(User user) throws Exception {
Context ctx = new Context();
ctx.add("userName", user.getName());
ctx.add("activationLink", generateActivationLink(user));
String html = engine.render("welcome-email.jhp", ctx);
emailClient.send(user.getEmail(), "Welcome!", html);
}
```
### Custom Functions
```java
FunctionLibrary lib = new FunctionLibrary();
lib.register("formatprice", (args, scopes) -> {
Number price = (Number) args.get(0);
return String.format("$%.2f", price.doubleValue());
});
JhpEngine engine = new JhpEngine(settings, lib);
```
**Template:**
```html
{{ formatprice(product.price) }}
```
## Configuration
```java
Settings settings = Settings.builder()
.base("/var/www/templates") // Base directory
.escape(true) // HTML escaping (default: true)
.maxIncludeDepth(15) // Max include depth (default: 15)
.issueHandleMode(IssueHandleMode.COMMENT) // Error handling mode
.build();
```
### Issue Handling Modes
- **COMMENT** - Render issues as HTML comments (default)
- **THROW** - Throw exceptions for issues
- **DEBUG** - Render detailed debug information
- **IGNORE** - Silently ignore issues
## Contributing
Contributions are welcome! Please feel free to submit pull requests or open issues.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Links
- **Documentation**: [docs/](docs/)
- **GitHub**: [java-hypertext-preprocessor](https://github.com/hind-sagar-biswas/java-hypertext-preprocessor/)
- **Maven Central**: [com.hindbiswas.jhp:jhp](https://search.maven.org/artifact/com.hindbiswas.jhp/jhp)
- **Issues**: [Issue Tracker](https://github.com/hind-sagar-biswas/java-hypertext-preprocessor/issues)
- **Publishing Guide**: [PUBLISHING.md](PUBLISHING.md)
- **Changelog**: [CHANGELOG.md](CHANGELOG.md)
## Acknowledgments
Inspired by:
- PHP's template syntax
- Jinja2 (Python)
- Blade (Laravel)
- Twig (Symfony)
---
Made with ❤️ by [Hind Sagar Biswas](https://github.com/hind-sagar-biswas)