vlaamscodex 0.1.3

A transpiler toolchain for Platskript, a parody programming language using Flemish dialect keywords that compiles to Python

VlaamsCodex

A transpiler toolchain for Platskript (.plats), a parody programming language that uses Flemish dialect keywords. VlaamsCodex compiles Platskript source code to Python and executes it.

Key Feature

After installation, you can run Platskript files directly with Python:

python examples/hello.plats

This "magic mode" works through Python's source encoding mechanism (PEP 263).

Installation

Option A: pipx (Recommended for End Users)

python -m pip install --user pipx
python -m pipx ensurepath
pipx install vlaamscodex

Option B: Virtual Environment

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install vlaamscodex

Option C: Development Installation

python -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e ".[dev]"

Usage

CLI Commands

Run a Platskript program:

plats run path/to/script.plats

Display generated Python code:

plats show-python path/to/script.plats

Compile to a Python file:

plats build path/to/script.plats --out output.py

Magic Mode

Platskript files begin with a Python encoding declaration:

# coding: vlaamsplats

After installing VlaamsCodex, execute directly with Python:

python path/to/script.plats

Quick Test

plats run examples/hello.plats
python examples/hello.plats

Expected output:

gdag aan weeireld

Example Program

# coding: vlaamsplats
plan doe
  zet naam op tekst weeireld amen

  maak funksie groet met wie doe
    klap tekst gdag plakt spatie plakt tekst aan plakt spatie plakt da wie amen
  gedaan

  roep groet met da naam amen
gedaan

How It Works

1. Python detects # coding: vlaamsplats (PEP 263) and requests the corresponding codec.
2. During normal startup, Python's site module processes .pth files in site-packages.
3. VlaamsCodex installs vlaamscodex_autoload.pth containing:

   import vlaamscodex.codec as _vc; _vc.register()
   

4. The register() function registers the vlaamsplats codec.
5. The codec decodes UTF-8 bytes, strips the encoding declaration, transpiles Platskript to Python, and returns valid Python source.
6. Python executes the generated code transparently.

Language Specification (v0.1)

Statements terminate with amen. Programs are wrapped in plan doe ... gedaan.

Statements

Syntax	Description
zet <var> op <expr> amen	Variable assignment
klap <expr> amen	Print expression
maak funksie <name> met <params...> doe ... gedaan	Function definition
roep <name> met <args...> amen	Function call
geeftterug <expr> amen	Return statement

Expressions

Syntax	Description
tekst <words...>	String literal (words joined by spaces)
getal <digits>	Numeric literal
da <name>	Variable reference
spatie	Space character literal
plakt	String concatenation operator

Limitations

• python -S: Disables site module, preventing .pth hook execution.
• python -I: Isolated mode restricts site-packages access.
• Fallback: Use plats run script.plats when magic mode is unavailable.

Troubleshooting

If you encounter SyntaxError: encoding problem: vlaamsplats:

1. Verify VlaamsCodex is installed in the active Python environment.
2. Ensure you are not using -S or -I flags.
3. Use plats run as an alternative.

Project Structure

src/vlaamscodex/     # Core implementation (compiler, codec, CLI)
data/                # Runtime artifacts (.pth startup hook)
examples/            # Sample Platskript programs
tests/               # Test suite
docs/                # Technical documentation

Documentation

• Overview
• How Python Runs It
• Packaging & Installation
• Language Specification
• Security Notes
• User Guide

Contributing

Contributions are welcome! Please read our Contributing Guidelines before submitting a pull request.

License

This project is licensed under the MIT License - see the LICENSE file for details.