README

# Introduction #

WebDyne is a dynamic content generation engine for Apache/mod_perl, PSGI web servers such as Plack and Starman, and PAGI runtimes. HTML documents with embedded Perl code are processed to produce dynamic HTML output.

An installer is included in the base WebDyne module for Apache, and wrapper scripts are included for PSGI, PAGI, and temporary local Apache/mod_perl development. Once WebDyne is installed any file with a `.psp` extension is treated as a WebDyne source file. It is parsed for WebDyne tags such as `<perl>` and `<block>`, which are interpreted and executed on the server as appropriate to generate a compliant HTML document. The resulting output is then sent to the browser.

Once parsed, pages are optionally stored in a partially compiled format, speeding up subsequent processing. The aim of WebDyne is to make coding web pages with Perl components a faster, easier and more enjoyable experience.

Full documentation for WebDyne (with examples) is available at [https://webdyne.org](https://webdyne.org).

# Overview #

WebDyne is primarily intended to operate as the main rendering and request-handling module within the wider WebDyne framework under a web server or application runtime. In current codebase terms that includes Apache/mod_perl, PSGI, and PAGI environments.

It can also be used directly from the command line or from standalone Perl scripts to render `.psp` templates to HTML, which makes it useful for diagnostics, testing, and simple offline generation.

WebDyne pages are HTML documents with embedded Perl and optional WebDyne-specific tags such as `<perl>`, `<block>`, `<include>`, processing instructions such as `<? ... ?>`, and shortcut tags such as `<start_html>`.

# WebDyne Features #

- server-side HTML rendering with embedded Perl
- a path from quick inline page logic to cleaner separation using `__PERL__`, modules, templates, and handler chains
- compile-time parsing and caching of `.psp` pages
- runtime flexibility across Apache/mod_perl, PSGI, PAGI, and standalone rendering tools

# Quick Example #

Save the following as `app.psp`:

```html
<html><head><title>Server Time</title></head><body>
The local server time is: <? localtime() ?>
</body></html>
```

You can render it directly from the command line:

```bash
wdrender app.psp
```

WebDyne supports sytactic shortcuts which still render as compliant HTML. 
The following produces the exact same output as the first example:

```html
<start_html title="Server Time">
The local server time is: <? localtime() ?>
```


Example output:

```html
<!DOCTYPE html><html lang="en"><head><title>Server Time</title><meta charset="UTF-8"></head>
<body><p>The local server time is: ...</p></body></html>
```

If you prefer to keep Perl logic in a dedicated section:

```html
<start_html title="Server Time">
The local server time is: <? print_time() ?>
__PERL__
sub print_time {
    print scalar localtime;
}
```

# Getting Started #

## Install the Core Module ##

Install WebDyne from CPAN using `cpan` or `cpanm`:

```bash
cpanm WebDyne
```

This installs the core WebDyne modules and command-line tools.

Depending on how you want to run WebDyne, you may also need additional runtime components:

- for PSGI: `Plack` and optionally a PSGI server such as `Starman`
- for Apache: Apache HTTP Server plus `mod_perl`
- for PAGI: the PAGI runtime stack

## Hello World ##

The fastest way to confirm WebDyne is working is to render a `.psp` file directly:

```bash
wdrender app.psp
```

You can also start the PSGI wrapper in test mode:

```bash
webdyne.psgi --test
```

Or serve a document root directory with the PSGI wrapper:

```bash
webdyne.psgi /path/to/site-root
```

The PAGI wrapper can be started in the same style:

```bash
webdyne.pagi --test
webdyne.pagi /path/to/site-root
```

For Apache/mod_perl development without installing system-wide Apache configuration, use the temporary Apache runner:

```bash
webdyne.apache --test
webdyne.apache /path/to/site-root
```

## A Simple PSGI Site ##

Create a directory with an `app.psp` file:

```html
<start_html>
My first WebDyne page. Server time: <? localtime() ?>
```

Then run:

```bash
webdyne.psgi /path/to/site-root/
```

WebDyne will serve `.psp` files from that directory through the PSGI runtime.

# Runtime Modes #

WebDyne can be used in several ways:

- Apache/mod_perl, either permanently configured or started locally through `webdyne.apache`
- PSGI, including wrapper usage through `webdyne.psgi`
- PAGI, including HTTP, server-sent event, WebSocket, and lifespan handling through `webdyne.pagi`
- standalone rendering through `wdrender`, `wdcompile`, or direct use of `WebDyne::html()`

# Features #

WebDyne supports:

- embedded Perl in HTML pages
- `<? ... ?>`, `<perl>...</perl>`, and related WebDyne tag styles
- compile-time parsing and cached intermediate representations
- template blocks and includes
- handler chains, session helpers, filters, and templates
- CGI-style parameter access from page code
- standalone rendering and debugging tools

# Further Reading #

Repository documentation includes:

- `doc/webdyne.xml` as the definitive guide source
- `doc/webdyne.md`
- `lib/WebDyne.pm.md`
- command documentation in `bin/*.md`

Useful entry points include:

- `bin/wdrender.md`
- `bin/wdcompile.md`
- `bin/webdyne.apache.md`
- `bin/webdyne.psgi.md`
- `bin/webdyne.pagi.md`
