SPLT32K - HTML to PL/SQL Compiler

A VS Code extension that compiles HTML templates with PL/SQL injections into PL/SQL procedures using htp.p/prn calls, with PL/SQL-aware linting support. Templates use clean, conflict-free delimiters: <%= expression %> and <% statements %>.

Features

• Clean HTML Authoring: Write readable HTML with optional inline PL/SQL injections
• Smart Compilation: Automatically chunks large content and handles q-quote delimiter selection
• PL/SQL Import/Reverse Engineering: Import SPLT32K-generated PL/SQL procedures back to HTML templates
• PL/SQL-Aware Linting: Lint HTML, CSS, and JavaScript while ignoring PL/SQL injections and manual break lines
• Configurable: Extensive configuration options for different use cases

Quick Start

1. Install the extension
2. Open an HTML file
3. Add PL/SQL injections using <%= expression %> or <% statements %>
4. Run SPLT32K: Compile HTML → PL/SQL (htp.p) to generate PL/SQL code
5. Run SPLT32K: Lint (PL/SQL-aware) to validate HTML structure

Injection Syntax

Expression Injection

<h1>Welcome <%= user_name %></h1>
<p>Current time: <%= TO_CHAR(SYSDATE, 'DD-MON-YYYY HH24:MI:SS') %></p>

Generates:

htp.prn(q'[<h1>Welcome ]');
htp.prn(to_char(user_name));
htp.prn(q'[</h1>]');

Statement Injection

<% IF user_role = 'ADMIN' THEN %>
  <div class="admin-panel">Admin Controls</div>
<% END IF; %>

Generates:

IF user_role = 'ADMIN' THEN
    htp.prn(q'[<div class="admin-panel">Admin Controls</div>]');
END IF;

Manual Break Compatibility

Legacy manual break lines are ignored by the linter:

<div>
q'~<p>Some content~' || some_function() || q'~more content</p>~'
</div>

PL/SQL Import (Reverse Engineering)

The extension can import SPLT32K-generated PL/SQL procedures back to HTML templates. This is useful for:

• Recovering lost HTML templates from compiled PL/SQL code
• Migrating between environments where only PL/SQL procedures are available
• Code review and maintenance of existing procedures

How Import Works

1. Verification: Checks that the PL/SQL procedure was generated by SPLT32K (looks for htp.p/prn calls, q-quote patterns, and proper structure)
2. Parsing: Extracts HTML content from htp.p/prn calls and reconstructs PL/SQL injections
3. Reconstruction: Rebuilds the original HTML template with <%...%> and <%=...%> syntax

Using Import

1. Open a PL/SQL (.sql) file containing a SPLT32K-generated procedure
2. Run SPLT32K: Import PL/SQL → HTML Template
3. The extension will create a new .splt32k.html file with the reconstructed template
4. Choose to save the file or save it with a custom name

Import Example

Original PL/SQL procedure:

CREATE OR REPLACE PROCEDURE my_page AS
BEGIN
    owa_util.mime_header('text/html', FALSE);
    owa_util.http_header_close;
    
    htp.prn(q'[<h1>Welcome ]');
    htp.prn(to_char(user_name));
    htp.prn(q'[</h1>]');
    
    IF user_role = 'ADMIN' THEN
        htp.prn(q'[<div class="admin-panel">Admin Controls</div>]');
    END IF;
END;

Reconstructed HTML template:

<h1>Welcome <%= user_name %></h1>
<% IF user_role = 'ADMIN' THEN %>
<div class="admin-panel">Admin Controls</div>
<% END IF; %>

Commands

• SPLT32K: Compile HTML → PL/SQL (htp.p): Generate PL/SQL procedure from HTML template
• SPLT32K: Import PL/SQL → HTML Template: Reverse-engineer a SPLT32K-generated PL/SQL procedure back to HTML template
• SPLT32K: Lint (PL/SQL-aware): Run HTML linting with PL/SQL injection awareness

Configuration

Basic Settings

{
  "splt32k.target.objectName": "${fileBasenameNoExtension}",
  "splt32k.chunkSize": 15000,
  "splt32k.usePrn": true,
  "splt32k.addMimeHeader": true,
  "splt32k.minifyHtml": false,
  "splt32k.wrapToChar": true
}

Linting Settings

{
  "splt32k.lint.onSave": true,
  "splt32k.lint.ignoreManualBreakRegex": "q'~[\\s\\S]*?~'\\s*\\|\\|[\\s\\S]*?\\|\\|\\s*q'~",
  "splt32k.lint.enableJs": true,
  "splt32k.lint.enableCss": true
}

Generated PL/SQL Structure

/*
 * Generated by SPLT32K - HTML to PL/SQL Compiler
 * Procedure: example_page
 * Generated: 2025-09-30T12:00:00.000Z
 */

CREATE OR REPLACE PROCEDURE example_page
AS
BEGIN
    /* Set HTTP content type header */
    owa_util.mime_header('text/html', FALSE);
    owa_util.http_header_close;

    htp.prn(q'[<!DOCTYPE html>
<html>
<head>
    <title>Example Page</title>
</head>
<body>
    <h1>Welcome ]');
    
    /* Expression from line 8: <%= user_name %> */
    htp.prn(to_char(user_name));
    
    htp.prn(q'[</h1>
</body>
</html>]');

EXCEPTION
    WHEN OTHERS THEN
        htp.prn('<p>Error generating page: ' || SQLERRM || '</p>');
        RAISE;
END example_page;
/

Key Features

Smart Chunking

• Automatically splits large text content into chunks under 15KB (configurable)
• Prefers splitting at newline boundaries for readability
• Handles very large HTML files safely

Dynamic Q-Quote Selection

• Automatically selects q-quote delimiters that don't conflict with content
• Tries bracket pairs first, then single characters, then rare Unicode characters
• Falls back to string concatenation if no safe delimiter found

PL/SQL-Aware Linting

• Removes <%...%> and <%=...%> injections before HTML linting
• Ignores manual break lines matching configurable regex pattern
• Maps diagnostic line numbers back to original source
• Supports HTMLHint rules optimized for templates

Requirements

• VS Code 1.74.0 or higher
• Node.js dependencies (automatically installed):
  • html-minifier-terser for HTML minification
  • html-validate for modern HTML validation
  • eslint for JavaScript linting
  • stylelint for CSS linting

Examples

See the examples/ directory for sample HTML templates demonstrating various features:

• basic-template.html - Simple template with expressions
• complex-template.html - Advanced template with statements and conditions
• legacy-template.html - Template with manual break compatibility

Troubleshooting

Common Issues

1. "Linting shows false positives"

   • Adjust ignoreManualBreakRegex pattern in settings
   • Check that PL/SQL injections use correct <%...%> syntax
   • Use .splt32k.html files for better syntax highlighting

2. "Generated PL/SQL has compilation errors"

   • Check that expressions return VARCHAR2/CHAR types or enable wrapToChar
   • Verify that statement injections contain valid PL/SQL syntax

3. "Red squiggly lines in wrong positions"

   • Ensure you're using .splt32k.html files
   • Check the SPLT32K Diagnostics output for position mapping details

Debug Mode

Enable debug logging by setting:

{
  "splt32k.debug": true
}

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Changelog

0.1.0

• Initial release
• Basic HTML to PL/SQL compilation
• PL/SQL-aware HTML linting
• Oracle database integration
• Configurable chunking and quoting