# Features

## Current Features

- Python package structure using `pyproject.toml`.
- Command-line compiler entry point via `python -m pl1compinpy`.
- Generated API reference for all Python modules, classes, functions, and methods.
- Layered package organization:
  - `core` for AST and compiler orchestration
  - `frontend` for keywords, lexing, and parsing
  - `runtime` for calling-convention normalization
  - `codegen` for assembly text, executable lowering, and binary containers
- PL/1 lexer with contextual keyword metadata.
- PL/1 parser producing an AST for assignments, declarations, calls, procedures, labels, `DO` groups, and `IF/THEN/ELSE`.
- Parser support for `DO WHILE`, post-test `DO ... UNTIL`, and `SELECT`/`WHEN`/`OTHERWISE`.
- PL/I-style expression precedence for power, unary operators, multiplication/division, addition/subtraction, concatenation, comparison, logical AND, and logical OR.
- Keyword catalog covering PL/1 statements, declaration attributes, storage attributes, I/O words, conditions, and preprocessor/listing words.
- Python-like text emitter for early compiler validation.
- Python source output backend.
- JVM bytecode-style output backend.
- JVM `.class` file output targeting Java 17 classfile major version 61.
- .NET ILAsm-compatible CIL output backend.
- .NET executable emission through ILAsm when the Microsoft tool is installed.
- Assembly text emitters for:
  - `x586-windows`
  - `x586-macos`
  - `x86_64-windows`
  - `arm64-macos`
  - `arm64-windows`
- Executable pipeline:
  - source
  - lexer
  - parser
  - AST
  - executable mnemonics
  - machine code
  - executable container
- Runtime calling convention:
  - local variables allocated in stack frames
  - parameters pushed right to left
  - call by reference
  - call by name normalized to sorted call by reference
  - dynamic function table for user procedures
  - static runtime function table for runtime functions, I/O, allocation, VSAM, TCP/IP, SSL, and TLS helpers
  - call validation against function parameter and return descriptions
- Runtime storage and I/O:
  - heap allocation blocks
  - heap-backed arrays
  - `FLOAT` declarations
  - `PICTURE`/`PIC` pattern metadata and runtime formatting/parsing
  - fixed decimal and float conversion to/from picture-formatted text
  - `POINTER` variables
  - `BASED(pointer)` record storage bound to dedicated pointer locators
  - calculation engine with a typed numeric tower, casts, and expression evaluation
  - strings stored as two-byte length plus payload
  - PL/I-style file declarations
  - PL/I-style `OPEN`, `READ`, `WRITE`, and `CLOSE` file statements
  - Unix-style stream files
  - fixed-length `RECFM(F)` records
  - variable-length `RECFM(V)` records with a two-byte length prefix
  - text and binary record payloads
  - primitive TCP socket runtime with SSL/TLS descriptor support
  - file-like socket stream runtime for easier payload reads/writes
  - generic dispatch by argument type with lambda-backed alternatives
  - VSAM-style catalog/data components for KSDS, ESDS, RRDS, and LDS
  - VSAM `OPEN`, `WRITE`, `READ`, and `CLOSE` runtime dispatch for KSDS, ESDS, RRDS, and LDS
- Binary/container writers for:
  - `pe32-x586-windows`
  - `pe64-x86_64-windows`
  - `elf64-x86_64`
  - `elf64-aarch64`
  - `macho64-x86_64-macos`
  - `macho64-arm64-macos`
- Public linker facade classes for PE, ELF, and Mach-O executable containers.
- C-style runtime linkage plans for PE, ELF, Mach-O, JVM, and .NET targets.
- Native runtime startup/shutdown symbol references plus embedded runtime link manifests.
- Managed runtime references for JVM classpath and .NET assembly linkage.
- Unit tests for lexer, parser, compiler output, assembly output, and binary signatures.
- Packaged PL/I builtin source inclusion with a first `SUBSTR` builtin.
- Static PL/I builtin function table entries that require `DCL name BUILTIN;` before use.

## Supported PL/1 Subset

- Integer variable declarations.
- Floating-point declarations.
- Picture declarations such as `DCL AMOUNT PIC'ZZZ9.99';`.
- Array declarations such as `DCL A(10) FIXED BIN(31);`.
- Pointer and based declarations such as `DCL P POINTER; DCL REC BASED(P);`.
- Integer assignments.
- Arithmetic with `+`, `-`, `*`, and `/`.
- Power, concatenation, comparison, unary, and logical expression evaluation through the calculation engine.
- Procedure calls.
- Function calls resolved and checked through runtime and dynamic function tables.
- Basic output through `CALL DISPLAY(...)`, `CALL PRINT(...)`, and basic `PUT LIST(...)`.
- Record I/O statements using forms such as `OPEN FILE(F);`, `READ FILE(F) INTO(BUF);`, `WRITE FILE(F) FROM(BUF);`, and `CLOSE FILE(F);`.
- Primitive runtime socket I/O for plain TCP, SSL, and TLS sockets.
- File-like socket payload I/O with Unix-style, `RECFM(F)`, and `RECFM(V)` framing.
- Procedure calls with by-reference and by-name normalization.
- File declarations using `FILE`, `RECORD`, `INPUT`, `OUTPUT`, `ENVIRONMENT(RECFM(...), LRECL(...), PATH(...))`, `TEXT`, and `BINARY`.
- Generic declarations using `GENERIC(... WHEN(...))`.
- VSAM declarations using `ENVIRONMENT(VSAM(...), KEYOFFSET(...), KEYLENGTH(...))`.
- VSAM I/O statements using `OPEN FILE(...)`, `WRITE FILE(...) FROM(...)`, `READ FILE(...) KEY(...) INTO(...)`, ESDS `RBA(...)`, RRDS `RRN(...)`, LDS `RBA(...) LENGTH(...)`, and `CLOSE FILE(...)`.
- Runtime `SUBSTR` behavior using one-based positions, enabled in source with `DCL SUBSTR BUILTIN;`.
- `PROC OPTIONS(MAIN)` program entry point.
- `PROC RECURSIVE` metadata and ordinary recursive-call continuation semantics.
- `PROC RETURNS(...)` function return metadata.
- `IF/THEN/ELSE` comparisons using `=`, `^=`, `<>`, `<`, `<=`, `>`, and `>=`.
- `DO WHILE` and post-test `DO ... UNTIL` groups.
- `SELECT` with `WHEN` and `OTHERWISE`.
- Labels and simple procedure bodies.
- Simple `DO` groups.

## Planned Features

- Full declaration attribute validation.
- Complete PL/1 expression precedence and type semantics.
- Broader I/O support beyond starter console output.
- Complete platform runtime/linker integration for generated binaries.
- More complete x86_64 and ARM64 instruction encoders.
- Symbol tables, scopes, diagnostics, and semantic analysis.
- Integration tests that execute generated binaries on supported platforms.