Metadata-Version: 2.4
Name: pageql
Version: 0.1.0
Summary: A template language for embedding SQL inside HTML directly
Project-URL: Homepage, https://github.com/adamritter/pageql
Project-URL: Issues, https://github.com/adamritter/pageql/issues
Author: adamritter
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.7
Requires-Dist: uvicorn
Requires-Dist: watchfiles
Description-Content-Type: text/markdown

PageQL is a template / application language that is trying to be a modern version of embedding SQL inside HTML directly.

Usage: python pageql_server.py --db data.db --dir templates --port 8000 --create


## TODO before alpha release: use it for more concrete examples.
I believe the current state is great, of course it needs a pip install

## Core Philosophy

PageQL aims to simplify web development involving relational data by allowing direct embedding of SQL-like queries within HTML templates. It draws inspiration from ColdFusion Markup Language (CFML) but focuses specifically on rendering reactive relational data.

**Key Principles:**

*   **Data-Centric:** The primary goal is displaying and manipulating data from a relational database. It is *not* intended as a full-fledged backend language.
*   **Declarative Focus:** While control structures (`#if`, potentially `#each`) exist, extensive scripting is discouraged to maintain clarity and focus on data presentation.
*   **Leverages SQL:** PageQL relies on the underlying SQL engine for expression evaluation, rather than implementing its own complex expression language.

## Future Vision - Reactive Queries

A key long-term goal for PageQL is to support **live, reactive SQL queries**. The vision is for the HTML output to automatically update whenever the underlying data used by a query (e.g., within a `#from` block) changes in the database.

This goal is a primary driver behind several core design choices:

*   **Declarative Nature:** By using declarative tags like `#from` to define data requirements, the system can potentially understand the data dependencies of a template fragment.
*   **Minimal Scripting ("Logic-less"):** Limiting imperative scripting makes it feasible to analyze template dependencies statically. Complex scripting logic would make it extremely difficult, if not impossible, to reliably track which data changes should trigger which UI updates.
*   **Focus on SQL:** Leveraging the database allows potential integration with database-specific notification or change-tracking mechanisms (e.g., triggers, event systems, logical replication) in the future to power this reactivity.

By keeping the templates focused on declaring *what* data is needed rather than *how* to fetch and update it imperatively, PageQL aims to lay the groundwork for automatically reflecting database changes in the rendered HTML with minimal developer effort in future versions.

## Design Choices & Simplifications

To maintain focus and simplicity, several design choices have been made:

*   **Simplified Imports/Rendering:** A single `#import` tag for modules and a single `#render` tag for partials/snippets provide a consistent mechanism for code reuse.
*   **Basic Error Handling:** On encountering an error, processing stops, and the error is written to a debug output (details TBD). There is no complex exception handling mechanism.
*   **Database-Driven State:** Communication and state management between requests should primarily occur via the database, not through internal application state or direct communication tags.
*   **External Extensibility:** Extensibility is planned via external APIs, not through mechanisms within the template language itself.

**Features explicitly *out of scope* (currently):**

*   Complex backend logic
*   Direct file management
*   Built-in form generation tags
*   Direct internet protocol tags (HTTP requests, etc.)
*   Advanced application framework features (handled externally)

## Usage (Preliminary)

PageQL is intended to be run via a command-line tool. The basic usage involves pointing the tool at a directory of `.pageql` files and specifying the SQLite database to use.

```bash
pageql --db path/to/your/database.sqlite --dir ./templates --port 8080
```

*   `--db <path>`: (Required) Path to the SQLite database file.
*   `--dir <path>`: (Required) Path to the directory containing the PageQL template files (`.pageql`) to be served.
*   `--port <number>`: (Optional) Port number to run the development server on. Defaults to a standard port (e.g., 8000 or 8080).

*(Note: Actual command name and argument flags are subject to change.)*

## Proposed Tag Syntax

**Database/Query:**
*(Note: All database modification tags (`#insert`, `#update`, `#delete`) executed within a single request lifecycle are typically treated as a single atomic transaction. Processing stops on the first error, and prior modifications within the same request are rolled back.)*
*   `#from <table> [WHERE ...] [ORDER BY ...]`: Executes a `SELECT` query against a table (or potentially a view) and iterates over the results. Supports binding parameters (e.g., `:limit`).
*   `#view <name> from <table> [WHERE ...]`: Creates a reusable SQL view definition. Supports binding parameters (e.g., `:halfusers`).
*   `#insert into <table> [(col1, col2, ...)] values (val1, val2, ...)`: Executes an `INSERT` SQL command. The column list is optional if values are provided for all columns in order. Values (`val1`, `val2`, etc.) can be literals or bound parameters (e.g., `:form_field_name`).
*   `#update <table> set col1=val1, col2=val2, ... [WHERE ...]`: Executes an `UPDATE` SQL command. Values (`val1`, `val2`, etc.) can be literals or bound parameters.
*   `#delete from <table> [WHERE ...]`: Executes a `DELETE` SQL command. Supports binding parameters in the `WHERE` clause.

**Partials/Modules:**
*   `#render <partial> [param=value ...]`: Renders a partial (defined locally or imported), optionally passing parameters.
*   `#partial [public] <name>`: Defines a reusable partial block.
    *   **Public Access:** If the optional `public` keyword is included, the partial block becomes directly accessible via an HTTP GET request at the URL path `/<filename>/<partial_name>` (where `<filename>` is the name of the template file without the `.pageql` extension).
    *   **Base File Access:** Requests to the base URL path corresponding to the file (`/<filename>`) will render the *top-level content* of the file (code outside of any named `#partial` block).
    *   **Parameters:** For both access methods, URL query parameters are made available via the standard parameter binding mechanism (e.g., `:param_name`).
*   [NOT IMPLEMENTED] `#import <module> [as <alias>]`: Imports modules relative to the template root directory, optionally assigning an alias. Assumes `.pageql` extension (e.g., `#import "components/button"` loads `components/button.pageql`).

**Variable Manipulation:**
*   `#set :<variable> <expression> [from <table> [WHERE ...]]`: Sets a variable. The value can be a literal (string, integer, float, `NULL`), or the result of a SQL expression, optionally evaluated against a table with a `WHERE` clause.
*   `#param <name> [type=<type>] [optional | required] [default=<expression>] [min=<num>] [max=<num>] [minlength=<num>] [maxlength=<num>] [pattern="<regex>"]`: Declares and optionally validates an expected request parameter (URL query string or POST form variable) named `<name>`.
    *   **Behavior:** Choose `optional` or `required`. **If neither is specified, the default is `required`.**
        *   `required` (or default): Processing stops with an error if the parameter is missing and no `default` is provided.
        *   `optional`: Parameter may be missing. If missing and no `default` is given, `:<name>` is `NULL`.
    *   `default=<expression>`: Provides a default value if the parameter is missing from the request. If present, this prevents the `required` check from failing.
    *   **Validation:** Optional attributes (`type`, `min`/`max`, `minlength`/`maxlength`, `pattern`) enforce rules on the parameter's value (after applying the default, if applicable). If any validation fails, processing stops with an error.
    *   **Access:** The validated (and potentially defaulted) parameter value is made available as `:<name>`. Direct access via `:<name>` without this tag bypasses validation and defaults.

**Flow Control:**
*   `#if <expression>`: Conditional rendering based on an expression.
*   `#else`: Else condition within an `#if` block.
*   `#elif <expression>`: Else-if condition within an `#if` block.
*  [NOT IMPLEMENTED]  `#each collection`: (Potential loop/iteration construct over a collection, likely passed in params. Probably it should introduce :this param like in Handlebars)

**Debugging:**
*   `#dump <expression>`: Dumps a table / SQL expression with timing info
*   `#log <message>`: Writes a message to a log.

**Page Processing:**
*   `#statuscode <expression>`: Sets the HTTP response status code.
*   `#redirect <url_expression>`: Performs an HTTP redirect by setting the `Location` header and status code to 302.
*   [NOT IMPLEMENTED] `#header <name> <value_expression>`: Sets an HTTP response header. The `<name>` (e.g., `Cache-Control`, `"X-Custom-Header"`) and `<value_expression>` (e.g., `"no-cache"`, `:some_variable`) are required positional arguments. Must typically be used before any HTML output. Example: `#header Cache-Control "no-cache, no-store, must-revalidate"`
*   [NOT IMPLEMENTED] `#cookie <name> <expression> [options...]`: Sets an outgoing HTTP cookie. The `<name>` is a literal string, and the `<expression>` is evaluated to determine the cookie's value. Standard cookie options like `expires="..."`, `path="..."`, `domain="..."`, `secure`, and `httponly` can be provided as subsequent optional attributes. (Reading incoming cookies is handled via standard variable access, e.g., `:param_name` or potentially a dedicated scope like `:cookie_name`).
*   [NOT IMPLEMENTED] `#contenttype <expression>`: Sets the `Content-Type` HTTP response header (e.g., `text/html; charset=utf-8`).

## Parameter Binding & Output

PageQL uses a unified namespace for variables originating from different sources:
*   Request parameters declared and validated via `#param`.
*   Variables explicitly set using `#set`.
*   Columns selected within a `#from` loop (each column becomes a variable within the loop's scope).
*   Parameters passed to a partial via `#render <partial> param_name=value`.
*   (Potentially cookie values, details TBD).

The engine distinguishes between binding these variables *into* SQL queries and rendering their values *into* the HTML output.

**1. SQL Parameter Binding (`:param_name`)**

*   **Purpose:** To safely include dynamic values within SQL statements (`WHERE` clauses, `VALUES` lists, `SET` assignments in `#from`, `#insert`, `#update`, `#delete`, `#view`, `#set ... from`).
*   **Syntax:** Use a colon prefix followed by the parameter name (e.g., `:user_id`, `:search_term`, `:text`, `:id`, `:active_count`).
*   **Security:** **This is the ONLY safe way to include dynamic data in SQL queries.** It prevents SQL injection vulnerabilities by ensuring the database driver handles the value correctly, rather than simply concatenating strings. The colon prefix is **mandatory** in these SQL contexts.
*   **`#from` Scope:** Within a `#from` loop, each selected column is directly accessible as a parameter using the colon prefix (e.g., `{{ :column_name }}`).

**2. Output Rendering and Simple Conditions (`{{ }}` and `#if`)**

*   **Purpose:** To display variable values within the HTML template content or use them in simple conditional checks.
*   **Standard Syntax (`{{ :variable }}` or `#if :variable`):** Using the colon prefix is always valid and often preferred for consistency.
*   **Optional Colon Shorthand (`{{ variable }}` or `#if variable`):** The colon prefix (`:`) **can be omitted** *if and only if* the expression consists of a **single variable name**.
    *   Example: `{{ my_var }}` is allowed (equivalent to `{{ :my_var }}`).
    *   Example: `#if my_var` is allowed (equivalent to `#if :my_var`).
    *   This shorthand **cannot** be used for more complex expressions within `{{ }}` or `#if`. For instance, `{{ my_var + 1 }}` or `#if my_var > 0` would require evaluation by the SQL engine and thus necessitate the colon prefix for clarity and proper parsing (e.g., `#if :my_var > 0`). The exact handling of complex expressions within `{{ }}` is still under consideration, but simple variable output is the primary use case.
*   **HTML Escaped Output (`{{ expression }}` or `{{ variable }}`):**
    *   This is the default and recommended way to output data.
    *   It automatically escapes HTML special characters (like `<`, `>`, `&`) to prevent Cross-Site Scripting (XSS) attacks.
    *   **Context-Aware Quoting:** When used inside an HTML attribute value (`<input value={{ :username }}>` or `<input value={{ username }}>`) or within a `<script>` tag for generating JSON-like structures, it *should ideally* automatically wrap string values in appropriate quotes (`<input value="Adam">`). *(Implementation detail)*
*   **Raw/Unescaped Output (`{{{ expression }}}` or `{{{ variable }}}`):**
    *   Outputs the variable's value directly without any HTML escaping. The same optional colon rule applies.
    *   **Use with extreme caution!** Only use this if you are certain the variable contains safe, pre-sanitized HTML or content that should not be escaped. Incorrect use can easily lead to XSS vulnerabilities.

## Expressions

PageQL does not define its own expression language. Instead, it leverages the expression evaluation capabilities of the underlying SQL database engine (e.g., SQLite).

Expressions are primarily used in:
*   **`#if <expression>` / `#elif <expression>`:** To conditionally render blocks of content. The expression should evaluate to a boolean-like value (in SQLite, 0 is false, non-zero is true). If the expression is more complex than a single variable name, it **must** use the colon prefix for variables (e.g., `#if :count > 10`).
*   **`#set :<variable> <expression> [from ...]`:** To compute a value to assign to a variable. Variables used within the `<expression>` **must** use the colon prefix (e.g., `#set :total_price :quantity * :unit_price`).
*   **`WHERE <expression>` clauses:** Within database query tags (`#from`, `#update`, `#delete`, `#view`, `#set ... from`) to filter data. Variables **must** use the colon prefix (e.g., `WHERE user_id = :id`).
*   **Value clauses:** In `#insert` (`values (...)`), `#update` (`set col = ...`), `#cookie`, `#header`, `#redirect`. Variables **must** use the colon prefix.

**Allowed Expressions:**

Generally, you can use standard SQL expressions supported by your database, such as:
*   Comparisons (`=`, `!=`, `<`, `>`, `<=`, `>=`, `IS NULL`, `IS NOT NULL`, `LIKE`, `IN`)
*   Logical operators (`AND`, `OR`, `NOT`)
*   Basic arithmetic (`+`, `-`, `*`, `/`)
*   Standard SQL functions (e.g., `LOWER()`, `UPPER()`, `LENGTH()`, `SUBSTR()`, `DATE()`, aggregate functions like `COUNT`, `SUM`, `AVG`, `MAX`, `MIN`)

**Important:** Since expressions are evaluated by the database, their exact syntax and available functions depend on the specific SQL database being used (primarily SQLite in the initial design). Variables within these expressions must be prefixed with `:`.

Current example:

<!-- Define a reusable partial -->
{{#partial shownumusers}}
    Partial Scope: Half of the users is {{ halfusers }}
    <!-- Setting variable inside partial only affects partial scope -->
    {{#set halfusers 0 }}
    Partial Scope (after set): Half of the users is {{ halfusers }}
{{/partial}}

<!-- Do an inline query for older folks -->
<h2>All Adults</h2>
{{#from users WHERE age >= :limit ORDER BY age}}
  <p>{{ :name }} is {{ :age }} years old.</p>
{{/from}}

<!-- Set another global variable -->
{{#set halfusers COUNT(*)/2.0 from users}}

<!-- Render the partial -->
Initial render:
{{#render shownumusers}}

<!-- Render the partial, passing a parameter which overrides the global one *for that render* -->
Render with param:
{{#render shownumusers halfusers=3}}

<!-- Render again, it uses the global value -->
Render after param:
{{#render shownumusers}}

{{#dump users}}

<!-- Create a SQL view of minors -->
{{#view youngPeople from users WHERE age < :halfusers}}

{{#dump youngPeople}}

<h2>All Minors (Age < {{ halfusers }})</h2>
<table>
  <thead>
    <tr>
      <th>Name</th>
      <th>Age</th>
    </tr>
  </thead>
  <tbody>
    <!-- Use the view -->
    {{#from youngPeople}}
      <tr>
        <td>{{ name }}</td>
        <td>{{ age }}</td>
      </tr>
    {{/from}}
  </tbody>
</table>
