Skip to content

Commit 6001b74

Browse files
hind-sagar-biswashind-sagar-biswas
committed
Generated Documentation
1 parent c158f57 commit 6001b74

14 files changed

+4270
-0
lines changed

‎README.md‎

Lines changed: 259 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,259 @@
1+
# Java Hypertext Preprocessor (JHP)
2+
3+
[![Java](https://img.shields.io/badge/Java-25-orange.svg)](https://www.oracle.com/java/)
4+
[![Maven](https://img.shields.io/badge/Maven-3.6+-blue.svg)](https://maven.apache.org/)
5+
[![License](https://img.shields.io/badge/License-Open%20Source-green.svg)](LICENSE)
6+
7+
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.
8+
9+
## Features
10+
11+
- **Intuitive Syntax** - Clean, readable template syntax with `{{ }}` for output and `{% %}` for logic
12+
- **HTML Escaping** - Automatic HTML escaping by default to prevent XSS attacks
13+
- **Control Structures** - Full support for if/else, for, foreach, and while loops
14+
- **Template Includes** - Modular templates with include directives
15+
- **Built-in Functions** - Common string and utility functions out of the box
16+
- **Extensible** - Easy to add custom functions
17+
- **Thread-Safe** - Built for concurrent environments
18+
- **Template Caching** - Automatic AST caching for improved performance
19+
- **Flexible Error Handling** - Multiple modes for handling runtime issues
20+
21+
## Quick Start
22+
23+
### Installation
24+
25+
Add to your `pom.xml`:
26+
27+
```xml
28+
<dependency>
29+
<groupId>com.hindbiswas.jhp</groupId>
30+
<artifactId>jhp</artifactId>
31+
<version>1.0-SNAPSHOT</version>
32+
</dependency>
33+
```
34+
35+
### Basic Usage
36+
37+
```java
38+
import com.hindbiswas.jhp.*;
39+
import com.hindbiswas.jhp.engine.*;
40+
41+
// Create engine
42+
Settings settings = Settings.builder()
43+
.base("/path/to/templates")
44+
.build();
45+
FunctionLibrary lib = new FunctionLibrary();
46+
JhpEngine engine = new JhpEngine(settings, lib);
47+
48+
// Prepare context
49+
Context ctx = new Context();
50+
ctx.add("name", "Alice");
51+
ctx.add("age", 25);
52+
53+
// Render template
54+
String output = engine.render("welcome.jhp", ctx);
55+
```
56+
57+
**Template (welcome.jhp):**
58+
```html
59+
<h1>Hello {{ name }}!</h1>
60+
{% if (age >= 18) %}
61+
<p>You are an adult.</p>
62+
{% else %}
63+
<p>You are a minor.</p>
64+
{% endif %}
65+
```
66+
67+
## Template Syntax
68+
69+
### Output Variables
70+
71+
```html
72+
{{ variable }} <!-- HTML-escaped output -->
73+
{{{ rawHtml }}} <!-- Raw output (not escaped) -->
74+
```
75+
76+
### Control Structures
77+
78+
```html
79+
<!-- If Statement -->
80+
{% if (condition) %}
81+
Content
82+
{% elseif (otherCondition) %}
83+
Other content
84+
{% else %}
85+
Default content
86+
{% endif %}
87+
88+
<!-- For Loop -->
89+
{% for (i = 0; i < 10; i++) %}
90+
<p>Item {{ i }}</p>
91+
{% endfor %}
92+
93+
<!-- Foreach Loop -->
94+
{% foreach (item in items) %}
95+
<li>{{ item }}</li>
96+
{% endforeach %}
97+
98+
<!-- Include Template -->
99+
{% include 'header.jhp' %}
100+
```
101+
102+
### Functions
103+
104+
```html
105+
{{ touppercase(name) }}
106+
{{ tolowercase(email) }}
107+
{{ trim(input) }}
108+
{{ len(items) }}
109+
{{ now() }}
110+
```
111+
112+
## Documentation
113+
114+
Comprehensive documentation is available in the [`docs/`](docs/) directory:
115+
116+
- [Installation Guide](docs/installation.md)
117+
- [Getting Started](docs/getting-started.md)
118+
- [Template Syntax](docs/template-syntax.md)
119+
- [Control Structures](docs/control-structures.md)
120+
- [Functions](docs/functions.md)
121+
- [Context & Variables](docs/context-variables.md)
122+
- [Configuration](docs/configuration.md)
123+
- [Advanced Usage](docs/advanced-usage.md)
124+
- [API Reference](docs/api-reference.md)
125+
- [Examples](docs/examples.md)
126+
127+
## Building from Source
128+
129+
```bash
130+
# Clone the repository
131+
git clone https://github.com/hind-sagar-biswas/java-hypertext-preprocessor.git
132+
cd java-hypertext-preprocessor
133+
134+
# Build with Maven
135+
mvn clean install
136+
137+
# Run tests
138+
mvn test
139+
```
140+
141+
## Requirements
142+
143+
- Java 25 or higher (Java 24 supported)
144+
- Maven 3.6+
145+
- ANTLR 4.13.2 (automatically managed)
146+
147+
## Testing
148+
149+
The project includes comprehensive unit tests using JUnit Jupiter:
150+
151+
```bash
152+
mvn test
153+
```
154+
155+
**Test Coverage:**
156+
- 88 unit tests
157+
- Context and variable management
158+
- Settings and configuration
159+
- Function library (built-in and custom)
160+
- Template rendering and integration
161+
- AST node structures
162+
163+
## Examples
164+
165+
### Web Application
166+
167+
```java
168+
@GetMapping("/profile/{username}")
169+
public ResponseEntity<String> profile(@PathVariable String username) {
170+
User user = userService.findByUsername(username);
171+
172+
Context ctx = new Context();
173+
ctx.add("user", user.toMap());
174+
175+
String html = engine.render("profile.jhp", ctx);
176+
return ResponseEntity.ok().contentType(MediaType.TEXT_HTML).body(html);
177+
}
178+
```
179+
180+
### Email Templates
181+
182+
```java
183+
public void sendWelcomeEmail(User user) throws Exception {
184+
Context ctx = new Context();
185+
ctx.add("userName", user.getName());
186+
ctx.add("activationLink", generateActivationLink(user));
187+
188+
String html = engine.render("welcome-email.jhp", ctx);
189+
emailClient.send(user.getEmail(), "Welcome!", html);
190+
}
191+
```
192+
193+
### Custom Functions
194+
195+
```java
196+
FunctionLibrary lib = new FunctionLibrary();
197+
198+
lib.register("formatprice", (args, scopes) -> {
199+
Number price = (Number) args.get(0);
200+
return String.format("$%.2f", price.doubleValue());
201+
});
202+
203+
JhpEngine engine = new JhpEngine(settings, lib);
204+
```
205+
206+
**Template:**
207+
```html
208+
<span class="price">{{ formatprice(product.price) }}</span>
209+
```
210+
211+
## Configuration
212+
213+
```java
214+
Settings settings = Settings.builder()
215+
.base("/var/www/templates") // Base directory
216+
.escape(true) // HTML escaping (default: true)
217+
.maxIncludeDepth(15) // Max include depth (default: 15)
218+
.issueHandleMode(IssueHandleMode.COMMENT) // Error handling mode
219+
.build();
220+
```
221+
222+
### Issue Handling Modes
223+
224+
- **COMMENT** - Render issues as HTML comments (default)
225+
- **THROW** - Throw exceptions for issues
226+
- **DEBUG** - Render detailed debug information
227+
- **IGNORE** - Silently ignore issues
228+
229+
## Contributing
230+
231+
Contributions are welcome! Please feel free to submit pull requests or open issues.
232+
233+
1. Fork the repository
234+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
235+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
236+
4. Push to the branch (`git push origin feature/amazing-feature`)
237+
5. Open a Pull Request
238+
239+
## License
240+
241+
This project is open source. Check the repository for license details.
242+
243+
## Links
244+
245+
- **Documentation**: [docs/](docs/)
246+
- **GitHub**: [java-hypertext-preprocessor](https://github.com/hind-sagar-biswas/java-hypertext-preprocessor/)
247+
- **Issues**: [Issue Tracker](https://github.com/hind-sagar-biswas/java-hypertext-preprocessor/issues)
248+
249+
## Acknowledgments
250+
251+
Inspired by:
252+
- PHP's template syntax
253+
- Jinja2 (Python)
254+
- Blade (Laravel)
255+
- Twig (Symfony)
256+
257+
---
258+
259+
Made with ❤️ by [Hind Sagar Biswas](https://github.com/hind-sagar-biswas)

‎docs/README.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# Java Hypertext Preprocessor (JHP)
2+
3+
## Introduction
4+
5+
Java Hypertext Preprocessor (JHP) is 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.
6+
7+
## Features
8+
9+
- **Intuitive Syntax** - Clean, readable template syntax with `{{ }}` for output and `{% %}` for logic
10+
- **HTML Escaping** - Automatic HTML escaping by default to prevent XSS attacks
11+
- **Control Structures** - Full support for if/else, for, foreach, and while loops
12+
- **Template Includes** - Modular templates with include directives
13+
- **Built-in Functions** - Common string and utility functions out of the box
14+
- **Extensible** - Easy to add custom functions
15+
- **Thread-Safe** - Built for concurrent environments
16+
- **Template Caching** - Automatic AST caching for improved performance
17+
- **Flexible Error Handling** - Multiple modes for handling runtime issues
18+
19+
## Documentation
20+
21+
- [Installation](installation.md)
22+
- [Getting Started](getting-started.md)
23+
- [Template Syntax](template-syntax.md)
24+
- [Control Structures](control-structures.md)
25+
- [Functions](functions.md)
26+
- [Context & Variables](context-variables.md)
27+
- [Configuration](configuration.md)
28+
- [Advanced Usage](advanced-usage.md)
29+
- [API Reference](api-reference.md)
30+
- [Examples](examples.md)
31+
32+
## Quick Example
33+
34+
```java
35+
// Create engine
36+
Settings settings = Settings.builder()
37+
.base("/path/to/templates")
38+
.build();
39+
FunctionLibrary lib = new FunctionLibrary();
40+
JhpEngine engine = new JhpEngine(settings, lib);
41+
42+
// Prepare context
43+
Context ctx = new Context();
44+
ctx.add("name", "Alice");
45+
ctx.add("age", 25);
46+
47+
// Render template
48+
String output = engine.render("welcome.jhp", ctx);
49+
```
50+
51+
**Template (welcome.jhp):**
52+
```html
53+
<h1>Hello {{ name }}!</h1>
54+
{% if (age >= 18) %}
55+
<p>You are an adult.</p>
56+
{% else %}
57+
<p>You are a minor.</p>
58+
{% endif %}
59+
```
60+
61+
## License
62+
63+
This project is open source. Check the repository for license details.
64+
65+
## Contributing
66+
67+
Contributions are welcome! Please feel free to submit pull requests or open issues.

‎docs/SUMMARY.md‎

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,71 @@
1+
# Summary
2+
3+
## Introduction
4+
* [Overview](README.md)
5+
* [Installation](installation.md)
6+
* [Getting Started](getting-started.md)
7+
8+
## Template Language
9+
* [Template Syntax](template-syntax.md)
10+
* Displaying Data
11+
* HTML Escaping
12+
* Variables
13+
* Expressions
14+
* Operators
15+
* [Control Structures](control-structures.md)
16+
* If Statements
17+
* For Loops
18+
* Foreach Loops
19+
* While Loops
20+
* Break and Continue
21+
* Template Includes
22+
* [Functions](functions.md)
23+
* Built-in Functions
24+
* String Functions
25+
* Utility Functions
26+
* Custom Functions
27+
* Function Composition
28+
29+
## Data Management
30+
* [Context & Variables](context-variables.md)
31+
* Creating Context
32+
* Adding Variables
33+
* Data Types
34+
* POJO Conversion
35+
* Variable Scope
36+
* Best Practices
37+
38+
## Configuration
39+
* [Configuration](configuration.md)
40+
* Settings Builder
41+
* Base Directory
42+
* HTML Escaping
43+
* Include Depth
44+
* Issue Handling
45+
46+
## Advanced Topics
47+
* [Advanced Usage](advanced-usage.md)
48+
* Template Caching
49+
* Thread Safety
50+
* Custom Function Library
51+
* Error Handling Strategies
52+
* Performance Optimization
53+
* Integration Patterns
54+
55+
## Reference
56+
* [API Reference](api-reference.md)
57+
* Core Classes
58+
* JhpEngine
59+
* Context
60+
* Settings
61+
* FunctionLibrary
62+
* Enums
63+
* Exceptions
64+
* [Examples](examples.md)
65+
* Basic Examples
66+
* Web Application
67+
* Email Templates
68+
* Blog System
69+
* E-commerce Product Page
70+
* Dashboard with Charts
71+
* Multi-language Support

0 commit comments

Comments
 (0)