htvl-lang 0.2.0__tar.gz

htvl_lang-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020-2026 Nicholas Rotich and HTVL contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

htvl_lang-0.2.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: htvl-lang
+Version: 0.2.0
+Summary: HTVL - a tiny HTML transpiler: write .htvl files, get HTML.
+Author: Nicholas Rotich, HTVL contributors
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/moinonin/htvl
+Project-URL: Repository, https://github.com/moinonin/htvl
+Project-URL: Bug Tracker, https://github.com/moinonin/htvl/issues
+Project-URL: Changelog, https://github.com/moinonin/htvl/releases
+Keywords: html,transpiler,static-site,compiler,dsl
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Compilers
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pygments>=2.10; extra == "dev"
+Dynamic: license-file
+
+# HTVL — a tiny HTML transpiler
+
+[![tests](https://github.com/moinonin/htvl/actions/workflows/tests.yml/badge.svg)](https://github.com/moinonin/htvl/actions/workflows/tests.yml)
+
+Write short tag calls in `.htvl` files, get plain HTML out. No build step, no
+dependencies, no framework — just a small, well-tested compiler you can read
+in an afternoon.
+
+```text
+$(h 1 '' '' 'Hello HTVL' '')
+```
+
+compiles to
+
+```html
+<h1 class="" id="" style="">Hello HTVL</h1>
+```
+
+## Install
+
+```bash
+pip install .          # from a clone of this repository
+```
+
+or run it straight from the checkout with zero installation:
+
+```bash
+python3 -m htvl compile
+```
+
+Python 3.10+, standard library only.
+
+## Quickstart
+
+```bash
+htvl new mysite        # scaffold: index.htvl, templates/, assets/
+cd mysite
+htvl compile           # writes public/index.html and copies assets/
+```
+
+A minimal project:
+
+```text
+mysite/
+├── index.htvl
+├── templates/
+│   └── headtags.htvl
+└── assets/
+```
+
+`index.htvl`:
+
+```text
+$DOCTYPE_htvl
+$htvl
+$head
+  $headtags
+$_head
+$body
+  $(nav 'navbar navbar-expand-md bg-dark navbar-dark')
+    $(a 'navbar-brand' './' 'Home' '' '' '' '')$_a
+    $(ul 'navbar-nav')
+    $_ul
+  $_nav
+
+  $(div 'container')
+    $(h 1 '' '' 'Hello HTVL' '')
+    $(p '' '' 'This page was compiled by the HTVL compiler.' '')
+    $_p
+  $_div
+$_body
+$_htvl
+```
+
+`templates/headtags.htvl`:
+
+```text
+$(title '' 'My HTVL page')
+$meta
+```
+
+Then `htvl compile` produces `public/index.html`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `htvl compile [path] [-o DIR] [--modern] [-w]` | Compile every `.htvl` file in `path` (default `.`) into `public/`; `.cal` files become CGI scripts in `cal/`; `assets/` is copied automatically. `--modern` emits clean, escaped HTML; `-w`/`--watch` keeps running and recompiles on change. |
+| `htvl check FILE... [--modern]` | Compile a single file to stdout — great for scripting and debugging. |
+| `htvl new NAME` | Scaffold a new project. |
+| `htvl list` | Print every tag signature and built-in variable. |
+
+### Legacy vs modern output
+
+The default output is byte-identical to the original 2020 compiler (empty
+attributes and all, guarded by `tests/test_golden.py`). For new projects, pass
+`--modern` to get clean HTML: empty attributes omitted, text escaped, no
+cosmetic quirks. Same source files, same line structure — only the rendering
+changes:
+
+```text
+$(div 'container')     legacy: <div class="container" id="" style="">
+                       modern: <div class="container">
+```
+
+### Watch mode
+
+```bash
+htvl compile --watch      # or: htvl compile -w
+```
+
+Compiles once, then keeps the output up to date as you edit:
+
+```text
+htvl: compiled public/index.html
+htvl: copied assets -> public/assets
+htvl: watching '/sites/mysite' (Ctrl-C to stop)
+htvl: compiled public/index.html        <- you saved index.htvl
+htvl: removed public/index.html         <- you deleted index.htvl
+htvl: stopped
+```
+
+Edits are incremental: changing `index.htvl` recompiles that file, changing
+anything in `templates/` rebuilds the project, changing `assets/` re-copies
+it, and deleting a source removes its output. A broken edit (an unknown tag,
+say) is reported but does not stop the watcher — fix the file and it picks up
+where it left off. No dependencies: it polls the filesystem a few times a
+second.
+
+Errors include the file, line and column, e.g.
+`htvl: error: unknown tag 'dvi' (line 12). Run 'htvl list' to see every available tag.`
+
+## The language
+
+* `$(tag 'arg' ...)` — tag calls, arguments are quoted strings (or bare words),
+  nesting allowed: `$(link stylesheet 'text/css' $(bsCdn '4.3.1'))`
+* `$name` — variables such as `$head`, `$_a`, `$meta`, and your own templates
+  (`$headtags`)
+* `$_name` — explicit closing tags
+* One source line = one output line; your indentation is your HTML's
+  indentation.
+
+The full reference — every tag signature, the variables, templates, CGI
+support — is in [docs/grammar.md](https://github.com/moinonin/htvl/blob/master/docs/grammar.md).
+
+### Editor support
+
+* **VS Code** — the extension lives in [`editors/vscode/`](https://github.com/moinonin/htvl/blob/master/editors/vscode):
+  ```bash
+  cd editors/vscode
+  npx @vscode/vsce package && code --install-extension htvl-*.vsix
+  ```
+  It highlights tag calls, variables (`$head`, `$_a`), quoted/bare arguments,
+  nested calls and HTML comments, and it is set up for comment blocks and
+  indentation-based folding.
+* **Anything Pygments-based** (Sphinx, MkDocs, code renderers) — a Pygments
+  lexer ships in [`extras/pygments_htvl.py`](https://github.com/moinonin/htvl/blob/master/extras/pygments_htvl.py):
+  ```python
+  from pygments.lexers import LEXERS
+  LEXERS["htvl"] = (
+      "pygments_htvl", "HTVL", ("htvl",), ("*.htvl", "*.cal"), ()
+  )
+  ```
+  Both are covered by the test suite.
+
+### Try it in the browser
+
+[`playground/`](https://github.com/moinonin/htvl/blob/master/playground) is a fully static, server-free playground: the
+page loads the **real Python compiler** compiled to WebAssembly with
+[Pyodide](https://pyodide.org) and compiles as you type, with a legacy/modern
+toggle. Open it from any static host:
+
+```bash
+python3 -m http.server 8000 --directory playground
+```
+
+## Using it as a library
+
+```python
+from htvl import compile_source
+
+html = compile_source("$(h 1 '' '' 'Hello' ')\n")
+```
+
+## About this repository
+
+HTVL started in 2020 as a two-line obfuscated bash script that generated HTML
+by `eval`-ing heredocs, complete with a 90-day trial timer that required
+`sudo`. That prototype is preserved untouched in [`legacy/`](https://github.com/moinonin/htvl/blob/master/legacy) — see
+[`legacy/README.original.md`](https://github.com/moinonin/htvl/blob/master/legacy/README.original.md) for the original
+documentation — together with a
+[de-obfuscated copy of its compiler](https://github.com/moinonin/htvl/blob/master/docs/recovered-legacy-compiler.sh) that
+serves as the authoritative definition of the grammar.
+
+This repository is the second act: the same language, reimplemented in Python
+as a readable, testable, dependency-free compiler:
+
+* `htvl/lexer.py` → `htvl/parser.py` → `htvl/elements.py` →
+  `htvl/emitter.py` — a classic tokenize / parse / render pipeline you can
+  actually read
+* the trial timer, the `sudo` asset copy and the silent failure modes are
+  gone; errors now name the line and column
+* `tests/test_golden.py` proves the port reproduces the original 2020 output
+  **byte for byte**, so existing `.htvl` files and `templates/*.sh` keep
+  working unchanged
+
+### Development
+
+```bash
+pip install -e ".[dev]"   # compiler + pytest + pygments (for the lexer tests)
+python3 -m pytest         # 136 tests, including the golden test
+```
+
+CI runs the suite on every push and PR: all supported Python versions
+(3.10–3.13) on Linux, spot-checks on macOS and Windows, and a packaging job
+that builds a wheel, installs it, and compiles a scaffolded project
+(`.github/workflows/tests.yml`).
+
+Release notes for v0.2.0 are in [docs/releases/v0.2.0.md](https://github.com/moinonin/htvl/blob/master/docs/releases/v0.2.0.md).
+
+### Roadmap
+
+* an opt-in `--modern` mode that fixes the documented `[legacy]` output
+  quirks (no empty attributes, proper escaping, real `role` support)
+* ~~watch mode and incremental builds~~ — **done in v0.2.0** (`htvl compile --watch`)
+* ~~syntax highlighting for `.htvl` files~~ — **done in v0.2.0** (VS Code
+  extension in `editors/vscode/`, Pygments lexer in `extras/`)
+* ~~a playground on the documentation site~~ — **done in v0.2.0**
+  (`playground/`, the real compiler running in-browser via Pyodide)
+
+## License
+
+MIT — see [LICENSE](https://github.com/moinonin/htvl/blob/master/LICENSE).

htvl_lang-0.2.0/README.md

@@ -0,0 +1,233 @@
+# HTVL — a tiny HTML transpiler
+
+[![tests](https://github.com/moinonin/htvl/actions/workflows/tests.yml/badge.svg)](https://github.com/moinonin/htvl/actions/workflows/tests.yml)
+
+Write short tag calls in `.htvl` files, get plain HTML out. No build step, no
+dependencies, no framework — just a small, well-tested compiler you can read
+in an afternoon.
+
+```text
+$(h 1 '' '' 'Hello HTVL' '')
+```
+
+compiles to
+
+```html
+<h1 class="" id="" style="">Hello HTVL</h1>
+```
+
+## Install
+
+```bash
+pip install .          # from a clone of this repository
+```
+
+or run it straight from the checkout with zero installation:
+
+```bash
+python3 -m htvl compile
+```
+
+Python 3.10+, standard library only.
+
+## Quickstart
+
+```bash
+htvl new mysite        # scaffold: index.htvl, templates/, assets/
+cd mysite
+htvl compile           # writes public/index.html and copies assets/
+```
+
+A minimal project:
+
+```text
+mysite/
+├── index.htvl
+├── templates/
+│   └── headtags.htvl
+└── assets/
+```
+
+`index.htvl`:
+
+```text
+$DOCTYPE_htvl
+$htvl
+$head
+  $headtags
+$_head
+$body
+  $(nav 'navbar navbar-expand-md bg-dark navbar-dark')
+    $(a 'navbar-brand' './' 'Home' '' '' '' '')$_a
+    $(ul 'navbar-nav')
+    $_ul
+  $_nav
+
+  $(div 'container')
+    $(h 1 '' '' 'Hello HTVL' '')
+    $(p '' '' 'This page was compiled by the HTVL compiler.' '')
+    $_p
+  $_div
+$_body
+$_htvl
+```
+
+`templates/headtags.htvl`:
+
+```text
+$(title '' 'My HTVL page')
+$meta
+```
+
+Then `htvl compile` produces `public/index.html`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `htvl compile [path] [-o DIR] [--modern] [-w]` | Compile every `.htvl` file in `path` (default `.`) into `public/`; `.cal` files become CGI scripts in `cal/`; `assets/` is copied automatically. `--modern` emits clean, escaped HTML; `-w`/`--watch` keeps running and recompiles on change. |
+| `htvl check FILE... [--modern]` | Compile a single file to stdout — great for scripting and debugging. |
+| `htvl new NAME` | Scaffold a new project. |
+| `htvl list` | Print every tag signature and built-in variable. |
+
+### Legacy vs modern output
+
+The default output is byte-identical to the original 2020 compiler (empty
+attributes and all, guarded by `tests/test_golden.py`). For new projects, pass
+`--modern` to get clean HTML: empty attributes omitted, text escaped, no
+cosmetic quirks. Same source files, same line structure — only the rendering
+changes:
+
+```text
+$(div 'container')     legacy: <div class="container" id="" style="">
+                       modern: <div class="container">
+```
+
+### Watch mode
+
+```bash
+htvl compile --watch      # or: htvl compile -w
+```
+
+Compiles once, then keeps the output up to date as you edit:
+
+```text
+htvl: compiled public/index.html
+htvl: copied assets -> public/assets
+htvl: watching '/sites/mysite' (Ctrl-C to stop)
+htvl: compiled public/index.html        <- you saved index.htvl
+htvl: removed public/index.html         <- you deleted index.htvl
+htvl: stopped
+```
+
+Edits are incremental: changing `index.htvl` recompiles that file, changing
+anything in `templates/` rebuilds the project, changing `assets/` re-copies
+it, and deleting a source removes its output. A broken edit (an unknown tag,
+say) is reported but does not stop the watcher — fix the file and it picks up
+where it left off. No dependencies: it polls the filesystem a few times a
+second.
+
+Errors include the file, line and column, e.g.
+`htvl: error: unknown tag 'dvi' (line 12). Run 'htvl list' to see every available tag.`
+
+## The language
+
+* `$(tag 'arg' ...)` — tag calls, arguments are quoted strings (or bare words),
+  nesting allowed: `$(link stylesheet 'text/css' $(bsCdn '4.3.1'))`
+* `$name` — variables such as `$head`, `$_a`, `$meta`, and your own templates
+  (`$headtags`)
+* `$_name` — explicit closing tags
+* One source line = one output line; your indentation is your HTML's
+  indentation.
+
+The full reference — every tag signature, the variables, templates, CGI
+support — is in [docs/grammar.md](https://github.com/moinonin/htvl/blob/master/docs/grammar.md).
+
+### Editor support
+
+* **VS Code** — the extension lives in [`editors/vscode/`](https://github.com/moinonin/htvl/blob/master/editors/vscode):
+  ```bash
+  cd editors/vscode
+  npx @vscode/vsce package && code --install-extension htvl-*.vsix
+  ```
+  It highlights tag calls, variables (`$head`, `$_a`), quoted/bare arguments,
+  nested calls and HTML comments, and it is set up for comment blocks and
+  indentation-based folding.
+* **Anything Pygments-based** (Sphinx, MkDocs, code renderers) — a Pygments
+  lexer ships in [`extras/pygments_htvl.py`](https://github.com/moinonin/htvl/blob/master/extras/pygments_htvl.py):
+  ```python
+  from pygments.lexers import LEXERS
+  LEXERS["htvl"] = (
+      "pygments_htvl", "HTVL", ("htvl",), ("*.htvl", "*.cal"), ()
+  )
+  ```
+  Both are covered by the test suite.
+
+### Try it in the browser
+
+[`playground/`](https://github.com/moinonin/htvl/blob/master/playground) is a fully static, server-free playground: the
+page loads the **real Python compiler** compiled to WebAssembly with
+[Pyodide](https://pyodide.org) and compiles as you type, with a legacy/modern
+toggle. Open it from any static host:
+
+```bash
+python3 -m http.server 8000 --directory playground
+```
+
+## Using it as a library
+
+```python
+from htvl import compile_source
+
+html = compile_source("$(h 1 '' '' 'Hello' ')\n")
+```
+
+## About this repository
+
+HTVL started in 2020 as a two-line obfuscated bash script that generated HTML
+by `eval`-ing heredocs, complete with a 90-day trial timer that required
+`sudo`. That prototype is preserved untouched in [`legacy/`](https://github.com/moinonin/htvl/blob/master/legacy) — see
+[`legacy/README.original.md`](https://github.com/moinonin/htvl/blob/master/legacy/README.original.md) for the original
+documentation — together with a
+[de-obfuscated copy of its compiler](https://github.com/moinonin/htvl/blob/master/docs/recovered-legacy-compiler.sh) that
+serves as the authoritative definition of the grammar.
+
+This repository is the second act: the same language, reimplemented in Python
+as a readable, testable, dependency-free compiler:
+
+* `htvl/lexer.py` → `htvl/parser.py` → `htvl/elements.py` →
+  `htvl/emitter.py` — a classic tokenize / parse / render pipeline you can
+  actually read
+* the trial timer, the `sudo` asset copy and the silent failure modes are
+  gone; errors now name the line and column
+* `tests/test_golden.py` proves the port reproduces the original 2020 output
+  **byte for byte**, so existing `.htvl` files and `templates/*.sh` keep
+  working unchanged
+
+### Development
+
+```bash
+pip install -e ".[dev]"   # compiler + pytest + pygments (for the lexer tests)
+python3 -m pytest         # 136 tests, including the golden test
+```
+
+CI runs the suite on every push and PR: all supported Python versions
+(3.10–3.13) on Linux, spot-checks on macOS and Windows, and a packaging job
+that builds a wheel, installs it, and compiles a scaffolded project
+(`.github/workflows/tests.yml`).
+
+Release notes for v0.2.0 are in [docs/releases/v0.2.0.md](https://github.com/moinonin/htvl/blob/master/docs/releases/v0.2.0.md).
+
+### Roadmap
+
+* an opt-in `--modern` mode that fixes the documented `[legacy]` output
+  quirks (no empty attributes, proper escaping, real `role` support)
+* ~~watch mode and incremental builds~~ — **done in v0.2.0** (`htvl compile --watch`)
+* ~~syntax highlighting for `.htvl` files~~ — **done in v0.2.0** (VS Code
+  extension in `editors/vscode/`, Pygments lexer in `extras/`)
+* ~~a playground on the documentation site~~ — **done in v0.2.0**
+  (`playground/`, the real compiler running in-browser via Pyodide)
+
+## License
+
+MIT — see [LICENSE](https://github.com/moinonin/htvl/blob/master/LICENSE).

htvl_lang-0.2.0/htvl/__init__.py

@@ -0,0 +1,44 @@
+"""HTVL - a tiny HTML transpiler.
+
+Public API::
+
+    from htvl import compile_source, compile_file, compile_project
+
+    html = compile_source("$(h 1 '' '' 'Hello' '')")
+"""
+
+from __future__ import annotations
+
+from .emitter import Emitter, emit
+from .errors import (
+    HtvlArityError,
+    HtvlError,
+    HtvlSyntaxError,
+    HtvlUnknownTagError,
+    HtvlUnknownVariableError,
+)
+from .parser import parse
+from .project import (
+    CompileResult,
+    compile_file,
+    compile_project,
+    compile_source,
+)
+
+__version__ = "0.2.0"
+
+__all__ = [
+    "__version__",
+    "compile_source",
+    "compile_file",
+    "compile_project",
+    "CompileResult",
+    "parse",
+    "emit",
+    "Emitter",
+    "HtvlError",
+    "HtvlSyntaxError",
+    "HtvlUnknownTagError",
+    "HtvlUnknownVariableError",
+    "HtvlArityError",
+]

htvl_lang-0.2.0/htvl/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for ``python -m htvl``."""
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())