PL1CompInPy

PL1CompInPy is a starter Python project for a PL/1 compiler.

Project Documents

The initial implementation provides a small compiler pipeline:

PL/1 Keyword Model

Classic PL/I does not reserve keywords globally. A word such as IF, CALL, or DECLARE can still be used as an identifier when the surrounding syntax makes that role clear. For that reason, PL1CompInPy keeps words as identifier tokens and attaches optional keyword metadata from pl1compinpy.keywords.KEYWORD_CATALOG.

The current catalog covers the main language-reference families:

Quick Start

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
python -m pl1compinpy --help

Compile a file:

python -m pl1compinpy examples/hello.pl1

Emit assembly instead of the default Python-like output:

python -m pl1compinpy examples/hello.pl1 --target python-source
python -m pl1compinpy examples/hello.pl1 --target jvm-bytecode
python -m pl1compinpy examples/hello.pl1 --target dotnet-il
python -m pl1compinpy examples/hello.pl1 --target x586-windows
python -m pl1compinpy examples/hello.pl1 --target x86_64-windows
python -m pl1compinpy examples/hello.pl1 --target x586-macos
python -m pl1compinpy examples/hello.pl1 --target arm64-macos
python -m pl1compinpy examples/hello.pl1 --target arm64-windows

Include packaged PL/I builtin source before compiling:

python -m pl1compinpy examples/hello.pl1 --builtin SUBSTR

Create a binary executable/container artifact:

python -m pl1compinpy examples/hello.pl1 --emit binary --binary-format pe32-x586-windows -o hello.exe
python -m pl1compinpy examples/hello.pl1 --emit binary --binary-format pe64-x86_64-windows -o hello-x64.exe
python -m pl1compinpy examples/hello.pl1 --emit binary --binary-format elf64-x86_64 -o hello-x86_64.elf
python -m pl1compinpy examples/hello.pl1 --emit binary --binary-format elf64-aarch64 -o hello-aarch64.elf
python -m pl1compinpy examples/hello.pl1 --emit binary --binary-format macho64-x86_64-macos -o hello-intel-macos
python -m pl1compinpy examples/hello.pl1 --emit binary --binary-format macho64-arm64-macos -o hello-m2-macos

Create a JVM .class file using Java 17 classfile version 61:

python -m pl1compinpy examples/backend/jvm_bytecode.pl1 --emit class -o PL1Program.class

Create a .NET executable using Microsoft ILAsm:

python -m pl1compinpy examples/backend/dotnet_il.pl1 --emit dotnet-exe -o PL1Program.exe

Run tests:

python -m unittest discover -s tests

Assembly Back Ends

The project includes backend emitters for:

Currently supported compiler features:

The emitters generate readable assembler text. They are intentionally small and direct so the runtime calling conventions and target-specific prologues can be refined as the compiler grows.

Binary Formats

The binary writer now follows the compiler pipeline:

PL/1 source -> lexer -> parser -> AST -> executable mnemonics -> machine code -> binary container

For example, a PL/1 assignment such as TOTAL = 40 + 2; is lowered into mnemonic operations such as MOV_EAX_IMM, PUSH_EAX, POP_EBX, ADD_EAX_EBX, and STORE_EAX_VAR, then encoded as machine-code bytes before being placed in the executable file.

The binary writer currently creates minimal executable/container files with correct platform signatures and source-derived starter code:

macOS uses Mach-O, not ELF. ELF is provided for Unix-style targets; Apple Intel and M2 targets use Mach-O containers.

The binary layer exposes explicit PE, ELF, and Mach-O linker classes in pl1compinpy.codegen.linkers. The pe32-x586-windows and pe64-x86_64-windows paths include source-driven instruction encoding for starter arithmetic and exit code. The ELF and Mach-O paths use the same mnemonic pipeline and have starter encoders for Intel and ARM64 machine code, ready to be expanded with full runtime I/O and platform linker details.

Runtime Model

The executable pipeline includes a first runtime calling convention:

The runtime also includes starter storage and I/O services:

Project Layout

PL1CompInPy/
  pyproject.toml
  docs/
    API.md
  scripts/
    generate_api_docs.py
  src/pl1compinpy/
    builtins/
      loader.py
      pl1/
        substr.pl1
    cli.py
    codegen/
      backends.py
      binary_formats.py
      dotnet_executable.py
      dotnet_il.py
      executable_pipeline.py
      jvm_bytecode.py
      python_source.py
    compiler.py
    core/
      ast.py
      compiler.py
    frontend/
      keywords.py
      lexer.py
      parser.py
    runtime/
      arrays.py
      based.py
      calculation.py
      calling.py
      function_table.py
      heap.py
      io.py
      picture.py
      socket_io.py
      strings.py
    vsam/
      catalog.py
      io.py
  tests/